.. _ChapterStartUpOptions: **************** 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 (:numref:`FaceLiveness Server Program Options`). .. _FaceLiveness Server Program Options: .. csv-table:: Face Liveness Server Program Options :header: "Argument", "Description" :widths: 30, 70 "**-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." "**--disable-duplicate-image-check**", "Disable the duplicate image check for all incoming requests to the server." "**--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. The username cannot be an empty string. | **Command Line Option Name** : --require-username | **Configuration File Parameter Name** : require-username | **Environment Variable Name** : KNOMI_FACE_LIVENESS_REQUIRE_USERNAME Disable Duplicate Image Check ---------------- | **Description** : Disable the duplicate image check for all incoming requests to /analyze and /checkLiveness endpoints. | **Command Line Option Name** : --disable-duplicate-image-check | **Configuration File Parameter Name** : disable-duplicate-image-check | **Environment Variable Name** : KNOMI_FACE_LIVENESS_DISABLE_DUPLICATE_IMAGE_CHECK 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. .. code-block:: :caption: *Logging configuration example* :name: 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