Start Up Options¶

FaceLiveness Server Program Options¶

By default the FaceLiveness servers is started on the localhost and only processes running on that system could access the server. Options can be specified via command line arguments, in the configuration file, or through environment variables. Options from the command line have the highest priority. Options from the configuration file are the second highest priority. Options from environment variables are the lowest priority. The FaceLiveness server provides the following startup arguments (FaceLiveness Server Program Options).

Face Liveness Server Program Options¶
Argument	Description
-h [ –help ]	Produce help message.
-c [ –config ]	Load configuration from specified file.
-l [ –log-config ]	Load log4cplus configuration from specified file.
–host	Set host name (default 0.0.0.0).
-p [ –port ]	Set port number (default 8080).
-u [ –url-path ]	URL base path.
–logged-image-path	Enable logging images to this directory.
–model-path	Path to face liveness model data files.
–device-brand-emulator-whitelist	Specifies a newline separated plain text file that specifies device brands that should not be evaluated by the emulator detection.
–device-model-emulator-whitelist	Specifies a newline separated plain text file that specifies device models that should not be evaluated by the emulator detection.
-t [ –concurrent-tasks ]	Set the maximum number of concurrent tasks. Defaults to number of cores available.
-q [ –queue-size ]	Set the maximum number of tasks that can be queued up. Defaults to unlimited.
–allowed-timestamp-seconds	How old an image timestamp is allowed to be without being rejected.
–allowed-future-timestamp-seconds	How far in the future an image timestamp is allowed to be without being rejected.
–disable-blur-detection	Disables evaluating incoming images for blur.
–require-username	Require all request packages contain the username element in order to process for liveness.
–certificate	Path to PEM certificate keystore file, enabling TLS.
–password	TLS certificate private key password (use if private key is encrypted).
–enable-cors	Enable Cross-Origin Resource Sharing.
–cors-acao-policy	Access-Control-Allow-Origin policy (default “*”).
–cors-acac-policy	Access-Control-Allow-Credentials policy (default “”).
–cors-aceh-policy	Access-Control-Expose-Headers policy (default “”).
–cors-acma-policy	Access-Control-Max-Age policy (default “”).
–cors-acam-policy	Access-Control-Allow-Methods policy (default “GET,POST,OPTIONS”).
–cors-acah-policy	Access-Control-Allow-Headers policy (default “Content-Type”).
–endpoint-decryption-key	Path to endpoint decryption key, enabling encrypted requests.
–password-encrypted	Encrypted password using symmetric key.
–password-decryption-iv	Initiation vector that was used to encrypt the password.
–password-decryption-key	File containing symmetric key to encrypt password.
–db-host	Transaction counting database host server.
–db-user	Transaction counting database login user name.
–db-pw	Transaction counting database login password.
–db-name	Transaction counting database name.
–db-poll-interval	OPTIONAL: Transaction counting database polling interval for reconnecting. Time in minutes. Default 5 minutes.

Help¶

Description : Produce help message.
Command Line Option Name : -h [ –help ]
Configuration File Parameter Name : N/A
Environment Variable Name : N/A

Configuration File¶

Description : Load configuration from specified file.
Command Line Option Name : -c [ –config ]
Configuration File Parameter Name : N/A
Environment Variable Name : KNOMI_FACE_LIVENESS_CONFIG

Log4Cplus Configuration¶

Description : Load log4cplus configuration from specified file.
Command Line Option Name : -l [ –log-config ]
Configuration File Parameter Name : log-config
Environment Variable Name : KNOMI_FACE_LIVENESS_LOG_CONFIG

Host Name¶

Description : Set the host name.  Default 0.0.0.0.
Command Line Option Name : –host
Configuration File Parameter Name : host
Environment Variable Name : KNOMI_FACE_LIVENESS_HOST

Port Number¶

Description : Set the port number.  Default 8080.
Command Line Option Name : -p [ –port ]
Configuration File Parameter Name : port
Environment Variable Name : KNOMI_FACE_LIVENESS_PORT

URL Path¶

Description : Set the URL base path.
Command Line Option Name : -u [ –url-path ]
Configuration File Parameter Name :  url-path
Environment Variable Name : KNOMI_FACE_LIVENESS_URL_PATH

Logged Image Path¶

Description : Enable logging images to the specified directory.
Command Line Option Name : –logged-image-path
Configuration File Parameter Name : logged-image-path
Environment Variable Name : KNOMI_FACE_LIVENESS_LOGGED_IMAGE_PATH

Model Path¶

Description : Path to face liveness model data files.
Command Line Option Name : –model-path
Configuration File Parameter Name : model-path
Environment Variable Name : KNOMI_FACE_LIVENESS_MODEL_PATH

Device Brand Emulator Whitelist¶

Description : Specifies a newline separated plain text file that specifies device brands that should not be evaluated by the emulator detection.
Command Line Option Name : –device-brand-emulator-whitelist
Configuration File Parameter Name : device-brand-emulator-whitelist
Environment Variable Name : KNOMI_FACE_LIVENESS_DEVICE_BRAND_EMULATOR_WHITELIST

Device Model Emulator Whitelist¶

Description : Specifies a newline separated plain text file that specifies device models that should not be evaluated by the emulator detection.
Command Line Option Name : –device-model-emulator-whitelist
Configuration File Parameter Name : device-model-emulator-whitelist
Environment Variable Name : KNOMI_FACE_LIVENESS_DEVICE_MODEL_EMULATOR_WHITELIST

Concurrent Tasks¶

Description : Set the meximum number of concurrent tasks.  Defaults to the number of cores available.
Command Line Option Name : -t [ –concurrent-tasks ]
Configuration File Parameter Name : concurrent-tasks
Environment Variable Name : KNOMI_FACE_LIVENESS_CONCURRENT_TASKS

Queue Size¶

Description : Set the maximum number of tasks that can be queued up.  Defaults to unlimited.
Command Line Option Name : -q [ –queue-size ]
Configuration File Parameter Name : queue-size
Environment Variable Name : KNOMI_FACE_LIVENESS_QUEUE_SIZE

Allowed Timestamp Seconds¶

Description : Specify how old an image timestamp is allowed to be without being reject.  Default is unlimited.
Command Line Option Name : –allowed-timestamp-seconds
Configuration File Parameter Name : allowed-timestamp-seconds
Environment Variable Name : KNOMI_FACE_LIVENESS_ALLOWED_TIMESTAMP_SECONDS

Allowed Future Timestamp Seconds¶

Description : Specify how far in the future an image timestamp is allowed to be without being rejected.  Default is unlimited.
Command Line Option Name : –allowed-future-timestamp-seconds
Configuration File Parameter Name : allowed-future-timestamp-seconds
Environment Variable Name : KNOMI_FACE_LIVENESS_ALLOWED_FUTURE_TIMESTAMP_SECONDS

Disable Blur Detection¶

Description : Disables evaluating incoming images for blur.
Command Line Option Name : –disable-blur-detection
Configuration File Parameter Name : disable-blur-detection
Environment Variable Name : KNOMI_FACE_LIVENESS_DISABLE_BLUR_DETECTION

Require Username¶

Description : Require all request packages contain the “username” meta data in order to process for liveness.
Command Line Option Name : –require-username
Configuration File Parameter Name : require-username
Environment Variable Name : KNOMI_FACE_LIVENESS_REQUIRE_USERNAME

Certificate¶

Description : Path to PEM certificate keystore file.  Enable TLS.
Command Line Option Name : –certificate
Configuration File Parameter Name : certificate
Environment Variable Name : KNOMI_FACE_LIVENESS_CERTIFICATE

Password¶

Description : TLS certificate private key password (use if private key is encrypted).
Command Line Option Name : –password
Configuration File Parameter Name : password
Environment Variable Name : KNOMI_FACE_LIVENESS_PASSWORD

Enable CORS¶

Description : Enable Cross-Origin Resource Sharing
Command Line Option Name : –enable-cors
Configuration File Parameter Name : enable-cors
Environment Variable Name : KNOMI_FACE_LIVENESS_ENABLE_CORS

CORS ACAO Policy¶

Description : Set the CORS Access-Control-Allow-Origin policy.  Default is “*”.
Command Line Option Name : –cors-acao-policy
Configuration File Parameter Name : cors-acao-policy
Environment Variable Name : KNOMI_FACE_LIVENESS_CORS_ACAO_POLICY

CORS ACAC Policy¶

Description : Set the CORS Access-Control-Allow-Credentials policy.  Default is “”.
Command Line Option Name : –cors-acac-policy
Configuration File Parameter Name : cors-acac-policy
Environment Variable Name : KNOMI_FACE_LIVENESS_CORS_ACAC_POLICY

CORS ACEH Policy¶

Description : Set the CORS Access-Control-Expose-Headers policy.  Default is “”.
Command Line Option Name : –cors-aceh-policy
Configuration File Parameter Name : cors-aceh-policy
Environment Variable Name : KNOMI_FACE_LIVENESS_CORS_ACEH_POLICY

CORS ACMA Policy¶

Description : Set the CORS Access-Control-Max-Age policy.  Default is “”.
Command Line Option Name : –cors-acma-policy
Configuration File Parameter Name : cors-acma-policy
Environment Variable Name : KNOMI_FACE_LIVENESS_CORS_ACMA_POLICY

CORS ACAM Policy¶

Description : Set the CORS Access-Control-Allow-Methods policy.  Default is “GET, POST, OPTIONS”.
Command Line Option Name : –cors-acam-policy
Configuration File Parameter Name : cors-acam-policy
Environment Variable Name : KNOMI_FACE_LIVENESS_CORS_ACAM_POLICY

CORS ACAH Policy¶

Description : Set the CORS Access-Control-Allow-Headers policy.  Default is “Content-Type”.
Command Line Option Name : –cors-acah-policy
Configuration File Parameter Name : cors-acah-policy
Environment Variable Name : KNOMI_FACE_LIVENESS_CORS_ACAH_POLICY

Endpoint Decryption Key¶

Description : Specify the path to the endpoint decryption key.  Enables encrypted requests.
Command Line Option Name : –endpoint-decryption-key
Configuration File Parameter Name : endpoint-decryption-key
Environment Variable Name : KNOMI_FACE_LIVENESS_ENDPOINT_DECRYPTION_KEY

Password Encryption¶

Description : Specify the encrypted password.
Command Line Option Name : –password-encrypted
Configuration File Parameter Name : password-encrypted
Environment Variable Name : KNOMI_FACE_LIVENESS_PASSWORD_ENCRYPTED

Password Decryption IV¶

Description : Specify the initiation vector used to encrypt the password.
Command Line Option Name : –password-decryption-iv
Configuration File Parameter Name : password-decryption-iv
Environment Variable Name : KNOMI_FACE_LIVENESS_PASSWORD_DECRYPTION_IV

Password Decryption Key¶

Description : Specify the file containing the symmetric key used to decrypt the password.
Command Line Option Name : –password-decryption-key
Configuration File Parameter Name : password-decryption-key
Environment Variable Name : KNOMI_FACE_LIVENESS_PASSWORD_DECRYPTION_KEY

DB Host¶

Description : Specify the transaction counting database host server.
Command Line Option Name : –db-host
Configuration File Parameter Name : db-host
Environment Variable Name : KNOMI_FACE_LIVENESS_DB_HOST

DB User¶

Description : Specify the transaction counting database login user name.
Command Line Option Name : –db-user
Configuration File Parameter Name : db-user
Environment Variable Name : KNOMI_FACE_LIVENESS_DB_USER

DB Password¶

Description : Specify the transaction counting database login password.
Command Line Option Name : –db-pw
Configuration File Parameter Name : db-pw
Environment Variable Name : KNOMI_FACE_LIVENESS_DB_PW

DB Name¶

Description : Specify the transaction counting database name.
Command Line Option Name : –db-name
Configuration File Parameter Name : db-name
Environment Variable Name : KNOMI_FACE_LIVENESS_DB_NAME

DB Poll Interval¶

Description : Specify the transaction counting database polling interval in minutes for reconnecting.  Default is 5 minutes.
Command Line Option Name : –db-poll-interval
Configuration File Parameter Name : db-poll-interval
Environment Variable Name : KNOMI_FACE_LIVENESS_DB_POLL_INTERVAL

Server Log Configuration¶

Logging in the Knomi REST server is provided by the log4cplus library. The face_liveness_log_config.ini configuration file is documented by the log4cplus project here. Knomi Face Liveness has two loggers, which are detailed below.

Info log¶

The info log contains general info and error output from the server. By default it is output to both face_liveness_info.txt and stdout. The format of the log can be controlled by the face_liveness_log_config.ini file using the “aw_face_liveness_rest_server_info” named logger.

Stats log¶

The stats log contains detailed information on each successful transaction processed by the server. By default it is output to both face_liveness_stats.js. The log content is a JSON per newline of the log, containing numerious fields describing the transaction. Below are some, but not all of the contained fields:

date - Unix timestamp of the time of the transaction.

duration - Time spent on the server (in seconds) handling the transaction (including network activity).

images - Contains information on where the logged images are saved.

input - The entire input request, with the images from the “frames” field removed.

result - The entire output request, with the returned image removed.

The log is controlled by the face_liveness_log_config.ini file using the “aw_face_liveness_rest_server_stats” named logger. It is not recommended to change the format of the stats log, as it is read directly by the Knomi Report Server.

Logging configuration example¶

# MyConsoleAppender
log4cplus.appender.MyConsoleAppender=log4cplus::ConsoleAppender
log4cplus.appender.MyConsoleAppender.layout=log4cplus::PatternLayout
log4cplus.appender.MyConsoleAppender.layout.ConversionPattern=[%-5p][%d] %m%n

# InfoLogAppender
log4cplus.appender.InfoLogAppender=log4cplus::DailyRollingFileAppender
log4cplus.appender.InfoLogAppender.File=./face_liveness_info.txt
log4cplus.appender.InfoLogAppender.layout=log4cplus::PatternLayout
log4cplus.appender.InfoLogAppender.layout.ConversionPattern=[%-5p][%d] %m%n
log4cplus.appender.InfoLogAppender.Schedule=MONTHLY
log4cplus.appender.InfoLogAppender.RollOnClose=false

# JsonAppender
log4cplus.appender.JsonAppender=log4cplus::DailyRollingFileAppender
log4cplus.appender.JsonAppender.File=./face_liveness_stats.js
log4cplus.appender.JsonAppender.layout=log4cplus::PatternLayout
log4cplus.appender.JsonAppender.layout.ConversionPattern=%m
log4cplus.appender.JsonAppender.Schedule=MONTHLY
log4cplus.appender.JsonAppender.RollOnClose=false

log4cplus.logger.aw_face_liveness_rest_server_info=DEBUG, MyConsoleAppender, InfoLogAppender
log4cplus.logger.aw_face_liveness_rest_server_stats=INFO, MyConsoleAppender, JsonAppender