Antivirus Service Configuration
Antivirus Configuration
Antivirus Scanner Type
The antivirus service currently supports ICAP and clamAV as antivirus scanners. The ANTIVIRUS_SCANNER_TYPE
environment variable is used to select the scanner. The detailed configuration for each scanner heavily depends on the scanner type selected. See the environment variables for more details.
-
For
icap
, only scanners using theX-Infection-Found
header are currently supported. -
For
clamav
, local Unix Domain Sockets and remote network sockets can be configured either by:-
pointing to a file like
/tmp/clamd.socket
or -
with a stream socket like
tcp://host.docker.internal:3310
.
-
Maximum Scan Size
Several factors can make it necessary to limit the maximum file size the antivirus service will use for scanning. Use the ANTIVIRUS_MAX_SCAN_SIZE
environment variable to scan only a given amount of bytes. Obviously, it is recommended to scan the whole file, but several factors like scanner type and version, bandwidth, performance issues, etc. might make a limit necessary.
Infected File Handling
The antivirus service allows three different ways of handling infected files. Those can be set via the ANTIVIRUS_INFECTED_FILE_HANDLING
environment variable:
-
delete: (default): Infected files will be deleted immediately, further post-processing is cancelled.
-
abort: (advanced option): Infected files will be kept, further post-processing is cancelled. Files can be manually retrieved and inspected by an admin. To identify the file for further investigation, the antivirus service logs the abort/infected state including the file ID. The file is located in the
storage/users/uploads
folder of the ocis data directory and persists until it is manually deleted by the admin via the Manage Unfinished Uploads command. -
continue: (not recommended - only for debugging): Infected files will be marked via metadata as infected but post-processing continues normally. Note: Infected Files are moved to their final destination and therefore not prevented from download which includes the risk of spreading viruses.
In all cases, a log entry is added declaring the infection, and handling method and a notification via the userlog
service is sent.
Scanner Inaccessibility
In case a scanner is not accessible by the antivirus service like a network outage, service outage, or hardware outage, the antivirus service uses the abort
case for further processing, independent of the actual setting made. In any case, an error is logged noting the inaccessibility of the scanner used.
Operation Modes
The antivirus service can scan files during post-processing
. on demand
scanning is currently not available and might be added in a future release.
Post-processing
The antivirus service will scan files during post-processing. It listens for a post-processing step called virusscan
. This step can be added in the environment variable POSTPROCESSING_STEPS
. Read the documentation of the postprocessing service for more details.
Event Bus Configuration
The Infinite Scale event bus can be configured by a set of environment variables.
|
Note that for each global environment variable, a service-based one might be available additionally. For precedences see Environment Variable Notes. Check the configuration section below.
Without the aim of completeness, see the list of environment variables to configure the event bus:
Envvar | Description |
---|---|
|
The address of the event system. |
|
The clusterID of the event system. Mandatory when using NATS as event system. |
|
Enable TLS for the connection to the events broker. |
|
Whether to verify the server TLS certificates. |
|
The username to authenticate with the events broker. |
|
The password to authenticate with the events broker. |
Configuration
Environment Variables
The antivirus
service is configured via the following environment variables. Read the Environment Variable Types documentation for important details. Column IV
shows with which release the environment variable has been introduced.
Deprecation Info | Deprecation Version | Removal Version | Deprecation Replacement |
---|---|---|---|
Changing the envvar type for consistency reasons. |
5.0 |
next-prod |
ANTIVIRUS_ICAP_SCAN_TIMEOUT |
Name | IV | Type | Default Value | Description |
---|---|---|---|---|
|
pre5.0 |
string |
|
The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'. |
|
pre5.0 |
bool |
false |
Activates pretty log output. |
|
pre5.0 |
bool |
false |
Activates colorized log output. |
|
pre5.0 |
string |
|
The path to the log file. Activates logging to this file if set. |
|
pre5.0 |
string |
127.0.0.1:9277 |
Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed. |
|
pre5.0 |
string |
|
Token to secure the metrics endpoint. |
|
pre5.0 |
bool |
false |
Enables pprof, which can be used for profiling. |
|
pre5.0 |
bool |
false |
Enables zpages, which can be used for collecting and viewing in-memory traces. |
|
pre5.0 |
bool |
false |
Activates tracing. |
|
pre5.0 |
string |
|
The type of tracing. Defaults to '', which is the same as 'jaeger'. Allowed tracing types are 'jaeger' and '' as of now. |
|
pre5.0 |
string |
|
The endpoint of the tracing agent. |
|
pre5.0 |
string |
|
The HTTP endpoint for sending spans directly to a collector, i.e. http://jaeger-collector:14268/api/traces. Only used if the tracing endpoint is unset. |
|
pre5.0 |
string |
delete |
Defines the behaviour when a virus has been found. Supported options are: 'delete', 'continue' and 'abort '. Delete will delete the file. Continue will mark the file as infected but continues further processing. Abort will keep the file in the uploads folder for further admin inspection and will not move it to its final destination. |
|
pre5.0 |
string |
127.0.0.1:9233 |
The address of the event system. The event system is the message queuing service. It is used as message broker for the microservice architecture. |
|
pre5.0 |
string |
ocis-cluster |
The clusterID of the event system. The event system is the message queuing service. It is used as message broker for the microservice architecture. Mandatory when using NATS as event system. |
|
pre5.0 |
bool |
false |
Whether to verify the server TLS certificates. |
|
pre5.0 |
string |
|
The root CA certificate used to validate the server’s TLS certificate. If provided ANTIVIRUS_EVENTS_TLS_INSECURE will be seen as false. |
|
pre5.0 |
bool |
false |
Enable TLS for the connection to the events broker. The events broker is the ocis service which receives and delivers events between the services. |
|
5.0 |
string |
|
The username to authenticate with the events broker. The events broker is the ocis service which receives and delivers events between the services. |
|
5.0 |
string |
|
The password to authenticate with the events broker. The events broker is the ocis service which receives and delivers events between the services. |
|
pre5.0 |
string |
clamav |
The antivirus scanner to use. Supported values are 'clamav' and 'icap'. |
|
pre5.0 |
string |
/run/clamav/clamd.ctl |
The socket clamav is running on. Note the default value is an example which needs adaption according your OS. |
|
pre5.0 |
int64 |
0 |
Timeout for the ICAP client. |
|
5.0 |
Duration |
5m0s |
Scan timeout for the ICAP client. Defaults to '5m' (5 minutes). See the Environment Variable Types description for more details. |
|
pre5.0 |
string |
icap://127.0.0.1:1344 |
URL of the ICAP server. |
|
pre5.0 |
string |
avscan |
The name of the ICAP service. |
|
pre5.0 |
string |
|
The maximum scan size the virus scanner can handle. Only this many bytes of a file will be scanned. 0 means unlimited and is the default. Usable common abbreviations: [KB, KiB, MB, MiB, GB, GiB, TB, TiB, PB, PiB, EB, EiB], example: 2GB. |
|
pre5.0 |
string |
|
A predefined outcome for virus scanning, FOR DEBUG PURPOSES ONLY! (example values: 'found,infected') |
YAML Example
-
Note the file shown below must be renamed and placed in the correct folder according to the Configuration File Naming conventions to be effective.
-
See the Notes for Environment Variables if you want to use environment variables in the yaml file.
# Autogenerated
# Filename: antivirus-config-example.yaml
file: ""
log:
level: ""
pretty: false
color: false
file: ""
debug:
addr: 127.0.0.1:9277
token: ""
pprof: false
zpages: false
tracing:
enabled: false
type: ""
endpoint: ""
collector: ""
infected-file-handling: delete
events:
endpoint: 127.0.0.1:9233
cluster: ocis-cluster
tls_insecure: false
tls_root_ca_certificate: ""
enable_tls: false
username: ""
password: ""
scanner:
type: clamav
clamav:
socket: /run/clamav/clamd.ctl
icap:
timeout: 0
scan_timeout: 5m0s
url: icap://127.0.0.1:1344
service: avscan
max-scan-size: ""