(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-1)=

```{eval-rst}
.. 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 (Default: 300)."
  "**--allowed-future-timestamp-seconds**", "How far in the future an image timestamp is allowed to be without being rejected (Default: 300)."
  "**--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."
  "**--disable-420-1-injection-algorithm**", "Disable the first injection algorithm added in Face Liveness 4.20."
  "**--device-metrics-log-path**", "Set the path to the device metrics log. To disabled, set to empty string. Default value is device_metrics_log.json."
  "**--device-metrics-url**", "Sets the URL when using a device metrics 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 300 seconds.

**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 300 seconds.

**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

### Disable 4.20 Injection Algorithm 1

**Description**

 : Disable the first injection detection algorithm added in Face Liveness version 4.20.

**Command Line Option Name**

 : --disable-420-1-injection-algorithm

**Configuration File Parameter Name**

 : disable-420-1-injection-algorithm

**Environment Variable Name**

 : KNOMI_FACE_LIVENESS_DISABLE_420_1_INJECTION_ALGORITHM

### Device Metrics Log Path

**Description**

 : Set the path to the device metrics log file. To disabled, set to empty string. Default value is device_metrics_log.json.

**Command Line Option Name**

 : --device-metrics-log-path

**Configuration File Parameter Name**

 : device-metrics-log-path

**Environment Variable Name**

 : KNOMI_FACE_LIVENESS_DEVICE_METRICS_LOG_PATH

### Device Metrics URL

**Description**

 : Set the URL to the device metrics server.

**Command Line Option Name**

 : --device-metrics-url

**Configuration File Parameter Name**

 : device-metrics-url

**Environment Variable Name**

 : KNOMI_FACE_LIVENESS_DEVICE_METRICS_URL

### 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](https://log4cplus.sourceforge.io/docs/html/classlog4cplus_1_1PropertyConfigurator.html#a21e8e6b1440cc7a8a47b8fd14c54b239). 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
```