Docker image published on OPSWAT Docker Hub

OPSWAT publish all official public docker images on Docker Hub:

opswat/metadefendercore-<os-type>:<version>

The docker images are all bundled with the official release MetaDefender Core.

Note:

To ensure better tracking of the running image version, it is advisable for users to not use the :latest tag when deploying containers in production.

Instead, it is recommended to specify a meaningful tag such as 5.13.2.

More information:

https://hub.docker.com/r/opswat/metadefendercore-debian

https://hub.docker.com/r/opswat/metadefendercore-rocky-nonroot

Pull from the OPSWAT Docker Hub repository

pull image
Copy
  • <repository> - OPSWAT repository address
  • <platform> - can be debian , rocky
  • <version> - desired Core version (optional, default is latest)

Example:

pull debian
Copy

Run MetaDefender Core Docker image

docker run cmd
Copy

For IKARUS, --shm-size=1gb should be added when starting the docker.

If you're using Kubernetes (K8S), the section below should be specified in the yaml file:

[Parameter] Container Name

Argument: --name <container_name>

Description: Your container’s name

Example: --name mdcore01

[Parameter] Init Details (Environmental Variables & Ignition File)

Argument: -v <ignition_folder>:<container_ignition_folder> -e "<env_var>=<value>"

Description:

You must configure MetaDefender Core (default local admin account, database connection etc.) before running MetaDefender Core docker image. It could be done via either one of following options (do not use all options, otherwise the ignition file settings will be ignore and overwritten):

  1. Using ignition file (-v)
  2. Using environmental variables (-e)
  3. Using IGNITION_JSON

Option 1: Using environmental variables

-e "<env_var>=<value>" : set an environmental variable to configure, each environmental variable need one -e argument.

Available environmental variables:

Environmental variableNecessity
DB_MODErequireddatabase mode
DB_TYPErequireddatabase type
DB_HOSTrequireddatabase host
DB_PORTrequireddatabase port
DB_USERrequireddatabase user
DB_PWDrequired

database password

Support some specific characters: */-+?&lt;&gt;:{}[]()*&^%$#@~`;.,

Not support " (double quotation) and ' (quotation).

MD_INSTANCE_NAMEoptional

instance name

Note: For deployments using a remote database type and multiple containers, avoid assigning the same instance name

MD_USERoptionalusername to create the first admin user
MD_PWDoptionalpassword to create the first admin user
MD_EMAILoptionalemail to create the first admin user
APIKEYoptionalthe API key will be assigned to the admin user for license auto deactivation, activation, HTTPS enabling, proxy enabling and health check enabling.
LICENSE_KEYoptionalan license key for license auto activation
STORAGE_PATHoptionala full path of storage for sanitized, DLP processed and quarantined files
DATA_DIRoptionala full path of MetaDefender Core working data directory
REST_ADDRESSoptionalREST binding address for MetaDefender Core’s Nginx to be allowed
REST_PORToptionalREST binding port for MetaDefender Core’s Nginx to be allowed
IGNITION_JSONoptional

The ignition file settings, only JSON format is accepted.

For example: IGNITION_JSON='{"user/name": "admin", "user/password": "admin", "user/email": "admin@local"}'

For database password, this support some specific characters: */-+?&lt;&gt;:{}[]()*&^%$#@~`;.,

Not support " (double quotation) and ' (quotation).

CORE_CONF_JSONoptional

MetaDefender Core configuration file settings, only JSON format is accepted.

For example: CORE_CONF_JSON='{"global/restport": "8009", "logger/loglevel": "info"}'

CORE_DATA_PATHoptional

a full path to folder (in container) storing all writable data (engine data, logs, runtime data, etc.).

Default is /opt/ometascan/core_data

Make sure to mount a volume to this folder to run with the policy.

CERT_PATHoptional

A full path to folder containing certificate file and private key file.

There files must have the same filename meanwhile its extensions must be .crt and .key

After being added, the filename without extension will be the name of the certificate in MetaDefender Core

MDCORE_CERT_PASSPHRASEoptional

A passphrase for encrypted private key when adding new certificate via CERT_PATH environment variable.

Passphrase must be less than or equal 1023 characters

Passphrase does not support single quote character '

MDCORE_SSL_PROTOCOLSoptionalSpecify the TLS version. Accepted values (case-insensitive): TLSv1.2,TLSv1.3
MDCORE_SSL_ADVANCED_CONFIGSoptional

Configure advanced SSL settings such as cipher suites, session timeout, and caching. Accepted values (case-insensitive):

ssl_verify_depth 10; ssl_session_cache none; *In case of using docker-compose, they should not input single quote ' and double quote "

MDCORE_DB_NAMEoptional

Used for customizing the PostgreSQL database name of MetaDefender Core.

By default, in shared DB mode, it is metadefender_core Name must begin with a letter (a-z) or underscore (_). Subsequent characters in a name can be letters, digits (0-9), or underscores. Maximum length is 63.

MDCORE_DB_PRIVATE_USERNAMEoptionalPostgreSQL server's internal user created for MetaDefender Core own operational purpose. If not specified, then MetaDefender Core will auto generate this user. Details: Customize Internal PostgreSQL User
MDCORE_DB_PRIVATE_PASSWORDoptionalPostgreSQL server's internal user password created for MetaDefender Core own operational purpose. If not specified, then MetaDefender Core will auto generate this user. Details: Customize Internal PostgreSQL User
PROXYrequire

true: Enable proxy feature.

false: Disable proxy feature.

PROXY_HOSTrequireProxy server
PROXY_PORTrequireProxy port
PROXY_USERoptionalUsername for proxy authentication
PROXY_PWDoptionalPassword for proxy authentication
PROXY_EXCLUSIONoptionalList of IPs to be added to proxy exception
MDCORE_HEALTH_CHECKoptional

true

  • Enable health check feature.
  • Set 3 health check criterias if customized.

false

  • Disable health check feature.
  • Ignore customized health check criteria.

not defined

  • Enable health check feature with
  • Queue threshold: 100
  • Minimum number of AVs: 0
  • List of requires engines: empty.
MDCORE_QUEUE_THRESHOLDoptional

Health check criteria.

Threshold for scan queue. Unit is %. Default: 100 (%).

When allocated slots percentage exceeds the threshold, MetaDefender Core will set itself unhealthy.

MDCORE_MINIMUM_NUMBER_AVoptional

Health check criteria.

Minimum number of AV engines. Default: 0. When number of active AV engines is less than or equal to the predefined value, MetaDefender Core will set itself unhealthy.

MDCORE_REQUIRED_ENGINESoptional

Health check criteria.

A list of mandatory engines. Default: all the engines of a license. When any predefined engines are not active, MetaDefender Core will set itself unhealthy.

UPGRADE_DBoptional

true

  • Enable database upgrade process. This migrates Workflow Rules and other settings.
  • Require MDCORE_UPGRADE_FROM_DB_NAMEvariable.
  • Require super-user permission for DB_USER.
  • Only support shared-database mode DB_MODE=4 and remote PostgreSQL DB_TYPE=remote .

false / not defined

  • Database upgrade process will not run.
MDCORE_UPGRADE_FROM_DB_NAMEoptional

Required when UPGRADE_DB = true

If this variable does not exist, upgrade process will exit with code 1.

MIGRATE_HISTORYoptional

Required when UPGRADE_DB = true

true

  • Database upgrade process migrates processing history, quarantine history, module update and configuration history.

false / not defined

  • Database upgrade process will not migrate these kinds of data.
MDCORE_LICENSE_COMMENToptional

Default: empty string

Add the comment for the license when activating.

OLMS_HOST_URLoptional

The OLMS server endpoint. If users want to use OLMS, this variable is required.

MetaDefender Core will treat OLMS higher priority than the normal way in license activation.

OLMS_TOKENoptionalToken created from OLMS server. If users want to use OLMS, this variable is required.
OLMS_RULEoptionalRule containing licenses from OLMS server. If users want to use OLMS, this variable is required.
OLMS_REST_PORToptional

Default: 8040

OLMS port for REST API.

OLMS_SOCKET_PORToptional

Default: 3316

OLMS port for socket interface.

OLMS_CONNECTION_TYPEoptional

Default: production

Can be production or hotbackup

OLMS_USE_PROXYoptional

Default: false

If the user want to use proxy for the OLMS activation

OLMS_PROXY_SERVERoptional

Default: empty string

Proxy server address

This field is required if OLMS_USER_PROXY is set to true

OLMS_PROXY_PORToptional

Default: empty string

Proxy port

This field is required if OLMS_USER_PROXY is set to true

OLMS_PROXY_PROXY_TYPEoptional

Default: empty string

Proxy type. Accepted values:

  • socks4
  • socks5
  • http

This field is required if OLMS_USER_PROXY is set to true

OLMS_PROXY_USERNAMEoptional

Default: empty string

Proxy username

OLMS_PROXY_PASSWORDoptional

Default: empty string

Proxy password

The priority for overriding configs is:

JSON environmental variable (IGNITION_JSON, CORE_CONF_JSON) > single environmetal variable

For example, the following command will start a container with global/restport=8009 , and ignore REST_PORT=8010 :

docker run -it --name core -p 8009:8009 \

-e DB_MODE=4 \

-e DB_TYPE=remote \

-e DB_HOST=192.168.0.1 \

-e DB_PORT=5432 \

-e DB_USER=postgres \

-e DB_PWD=admin \

-e REST_PORT=8010 \

-e IGNITION_JSON='{"user/name": "admin", "user/password": "admin", "user/email": "admin@local"}' \

-e CORE_CONF_JSON='{"global/restport": "8009", "logger/loglevel": "info"}' \

opswat/metadefendercore-debian:latest

If missing any of the required environmental variables, docker run will return failed with error message <ENV> is missing. Please set <ENV> before running container.

When deploying in a Kubernetes environment with multiple replicas and a remote database, avoid setting the same instance name across all Pods. Specifically, be cautious when using the MD_INSTANCE_NAME environment variable or the global/instance_name field in CORE_CONF_JSON. Using a shared instance name will cause all Pods to use the same database private user. If any Pod restarts, this private user’s password will be regenerated, resulting in the other Pods becoming non-functional.

Option 2: Using ignition file

-v <ignition_folder>:<container_ignition_folder> - (optional) mounting the folder containing the ignition file to the container’s folder

  • <ignition_folder> - ignition folder path containing the ignition file <ignition_folder>/ometascan.conf

  • <container_ignition_folder> - container’s folder to be mounted to /opt/ometascan/core_data/opswat (by default)

Example

Setup a PostgreSQL version 14 server. After that, we assume that remote PostgreSQL server’s information is

  • host = 192.168.0.1
  • port = 5432
  • user = postgres
  • password = admin
  • type = remote

In case of local PostgreSQL:

  • host = localhost
  • type = local

Option 1 - using environmental variables

env vars
Copy

Option 2 - using ignition file

ignition file
Copy

Option 3 - using ignition file with a full configuration package (.zip)

Note:

a. When using Local Update Folder, let's make sure pickupfolder (Pick up update from) in the settings_export.json is correct.

  • Format: <DATA_DIR>/path/to/update-folder
  • For example:
    • "pickupfolder": "/opt/ometascan/core_data/var/lib/ometascan/update_autoadd"

b. If you want to activate license or enable HTTPS during container starting, please make sure apikey of an administrator in .zip package matches with

  • apikey under [user] section (if present) in ignition file
  • or APIKEY environment variable (if present)
ignition file
Copy

[Parameter] User

Argument: -u <user ID>

Description: [Optional] run container with any user ID (UID) or group ID (GID). Range: [1000, 65533]

If not specified, the container will run as root user. Otherwise, a user will be used for non-root option.

Example: -u 1011

When running container with non-root user (-u <user ID> param), you are expected to grant write permission to the _ignition folder _and _ignition file_for a user with the respectively uid on the host machine, before running the container. There are 2 ways to do this:

  1. Grant write permission for others (e.g. chmod 777)
  2. Change owner to uid 1011 or gid 1011 (e.g. chown 1011:1011), then grant write permission for owner or group owner (e.g.: chmod 755)

[Parameter] Host Folder

Argument: -v <host_folder>:<container_folder>

Description: [Optional] mounting any additional folder from your host to the container (for managing config file, persistent data, storing log)

Example: -v /var/mdcore:/temp

[Parameter] REST Port

Argument: -p <rest_port>:<internal_port>

Description: Port on the host machine to map with Core REST and web console management port

Example: -p 30808:8008

[Parameter] Image Name

Argument: <image_name>

Description: MetaDefender Core docker image was built/pulled earlier

Example: mdcore:debian

Start / Stop container

start container
Copy
docker stop
Copy
  • <container_name> - container’s name for using later
  • <timeout> - timeout in second before Docker forces stop the container, this can result in lost data and restart the container abnormally, so this need to be set to long timeout, minimum 30 is recommended.

Example:

docker stop
Copy

Access to view MetaDefender Core logs

get logs
Copy
  • <container_name> - container’s name for using later
  • [-f] - keep following the log
  • [-n <number_of_lines>] - number of last lines existed in log file will be shown instantly when running this command.

Example:

tail logs
Copy

Collecting Logs by Generating a Support Package

Bash
Copy
  • <container_name>: The name of the container.
  • <support-package-file>.tar.gz: The generated support package file. You can find the file name in the console output after executing the command in Step 1.
  • <target_folder>: The destination folder on the host machine where the support package file will be saved.

Example:

Bash
Copy

Configure MetaDefender settings

You can modify the /etc/ometascan/ometascan.conf file. It can be modified in 2 ways:

  • Directly inside the container by using docker exec to go inside the container and modify
  • Mount the /etc/ometascan folder to host when starting the container, then modify the file on host folder

Database Maintenance

Bash
Copy
  • <container_name>: The name of the container.

Reference: Database Maintenance | MetaDefender Core 4.19.0 or above

Type to search, ESC to discard
Type to search, ESC to discard
Type to search, ESC to discard
Next to read:
Using build tool kit with your own docker image
On This Page
Docker image published on OPSWAT Docker HubPull from the OPSWAT Docker Hub repositoryRun MetaDefender Core Docker image[Parameter] Container Name[Parameter] Init Details (Environmental Variables & Ignition File)Option 1: Using environmental variablesOption 2: Using ignition fileExample[Parameter] User[Parameter] Host Folder[Parameter] REST Port[Parameter] Image NameStart / Stop containerAccess to view MetaDefender Core logsCollecting Logs by Generating a Support PackageConfigure MetaDefender settingsDatabase Maintenance