illumos: manual page: vscanadm.8

VSCANADM(8) Maintenance Procedures VSCANADM(8)

NAME

vscanadm - vscan service configuration utility

SYNOPSIS

vscanadm set -p property=value [-p property=value]...

vscanadm get [-p property]...

vscanadm import -p property filename

vscanadm export -p property filename

vscanadm validate -p property filename

vscanadm add-engine [-p property=value]... engine_id

vscanadm remove-engine engine_id

vscanadm set-engine -pproperty=value [-p property=value]... engine_id

vscanadm get-engine [-p property=value]... [engine_id]

vscanadm show

vscanadm stats [-z]

DESCRIPTION

The vscanadm command sets and displays properties of the vscan service,
vscand(8), and provides scan statistics.

File system exemption from virus scanning may be configured per file
system using the appropriate file system administrative command, for
example zfs(8).

Scan engines are third-party applications on external hosts that perform
the actual virus scanning operation on files. Multiple scan engines can
be configured for use by the vscan service. A minimum of two scan engines
is recommended. File scan requests are distributed among the configured
scan engines to achieve load balancing. A scan engine is identified by
its engine_id. The engine_id is a user defined string of up to 64 bytes.

The vscan service properties are divided into two categories: scan engine
properties, which are specific to a scan engine definition, and general
properties, which apply to the service and are not scan engine-specific.

SUBCOMMANDS

vscanadm recognizes the following subcommands:

vscanadm set -p property=value [-p property=value]...

Sets the values of vscan service general properties.

-p property=value
Specifies a property value

vscanadm get [-p property]...

Displays the values of vscan service general properties. If no
properties are specified, all vscan service general properties are
displayed.

-p property
Specifies a property value

The following properties are available for the vscanadm set and vscanadm
get subcommands:

max-size
The maximum size of files that should be virus
scanned. Files exceeding max-size are not scanned. The
max-size-action property determines whether access
should be allowed or denied to files that exceed max-
size.

The value of max-size is a string with a numeric
(decimal) component and an optional letter component
that specifies a unit size, in the format
"N[.N][KMGTP][B]".

Following the numeric component, the optional unit can
be specified as either one or two characters. For
example, either "K" or "KB" can be used to specify
kilobytes. Unit specifiers are not case-sensitive, and
must follow the numeric value immediately with no
intervening whitespace.

With either no unit specifier, or a unit specifier of
only "B", the numeric value is assumed to be in bytes.
The default value is 1GB.

Note that while the vscan service defines a maximum
file size for scanning, scan engines also typically
define their own maximum file size setting. It is
recommended that max-size be set to a value less than
or equal to the maximum file size for the scan
engine(s).

max-size-action
Specifies whether access will be allowed or denied to
files larger than max-size. Files larger than max-size
are not virus scanned. Valid values are:

allow
allow access to files larger than max-size
(no virus scan). This is the default value.

deny
deny access to files larger than max-size (no
virus scan)

vscanadm import -p property filename

Imports the property value from the specified file. The file must
contain a single line specifying the value of a single property.

vscanadm export -p property filename

Exports the property value to the specified file. The file must
contain a single line specifying the value of a single property.

vscanadm validate -p property filename

Validates the property value in the specified file. The file must
contain a single line specifying the value of a single property.

The following properties are available for the vscanadm import, vscanadm
export, and vscanadm validate subcommands:

types
A comma-separated list of file type extension matching rules.
This list defines which types of files are scanned and which
should be excluded during virus scanning. Each rule comprises
the rule indicator [+|-], followed by a file type expression
against which a file's type extension is compared. The file type
expression is case insensitive and may include the "*" and "?"
wildcards. There should be no whitespace between the rule
indicator and the file type expression. If a comma is included
within the file type expression, it must be escaped using a "\"
(backslash). A file type extension does not include its
preceding dot.

The rule indicator is a single character and can be one of:

+ include file type in virus scanning
- exclude file type from virus scanning

When a file is being evaluated as a candidate for virus
scanning, its file type will be compared with the rules defined
in types. The first rule matched will be applied. If no match is
found, the file will be virus scanned. The total length of the
types string can not exceed 4096 bytes. The default content of
the types list is "+*".

vscanadm add-engine [-p property=value]... engine_id

Adds a new scan engine identified by engine_id. The default values
are used for any scan engine properties that are not specified. The
hostname defaults to the engine_id.

-p property=value
Specifies a property value

vscanadm remove-engine engine_id

Remove scan engine identified by engine_id, removing all of its
configuration property values.

vscanadm set-engine -pproperty=value [-p property=value]... engine_id

Creates or updates the configuration property values for the scan
engine identified by engine_id.

-p property=value
Specifies a property value

vscanadm get-engine [-p property=value]... [engine_id]

Displays the values of the specified scan engine properties for the
scan engine identified by engine_id. If no engine_id is specified,
this subcommand displays the specified scan engine property values
for all configured scan engines. If no properties are specified, this
subcommand displays all vscan service scan engine properties.

-p property=value
Specifies a property value

The following properties are available for the vscanadm add-engine,
vscanadm remove-engine, vscanadm set-engine, and vscanadm get-engine
subcommands:

enable
Specifies whether the scan engine is enabled or
disabled. Valid values are "on" (enabled) and "off"
(disabled). The default is "on" (enabled). A scan
engine cannot be enabled if its host property is
invalid.

host
Hostname or IPv4 format IP address of the scan engine.

port
ICAP port number of the scan engine. The numeric value
ranges from 0 to 65535. The default ICAP port is 1344.

max-connection
The maximum number of concurrent connections that may
be established with a scan engine. The numeric value
ranges from 1 to 512. This property defaults to 8.

vscanadm show
Displays the values of all vscan service general
properties and scan engine properties.

vscanadm stats [-z]
Displays or resets the following vscan service
statistics:

o number of files scanned

o number of infected files

o number of failed scan requests

o scan errors (including a per scan
engine error count)

-z
Resets vscan service statistics counters to
zero

EXAMPLES

Example 1: Setting the Maximum Size Limit

To set the maximum size limit for files to be virus scanned to 128
megabytes, enter

# vscanadm set -p max-size=128M

Example 2: Allowing Access to Files

To allow access to files exceeding the maximum file size, enter

# vscanadm set -p max-size-action=allow

Example 3: Setting File Types

To set the types so that only files of type "odt", "exe" and "jpg" are
virus scanned, enter

# vscanadm set -p types=+odt,+exe,+jpg,-*

To set the types so that all file types except "doc" are virus scanned,
enter

# vscanadm set -p types=-doc,+*

Example 4: Displaying the File Types List

To display the file types list, enter

# vscanadm get -p types

Example 5: Adding the Scan Engine

To add the scan engine "my_eng" using the default values, enter

# vscanadm add-engine my_eng

Example 6: Disabling the Scan Engine

To disable the scan engine "my_eng", enter

# vscanadm set-engine -p enable=off my_eng

Example 7: Displaying Scan Engine Properties

To display the properties of the scan engine "my_eng", enter

# vscanadm get-engine my_eng

Example 8: Removing Scan Engine

To remove the scan engine "my_eng", enter

# vscanadm remove-engine my_eng

Example 9: Displaying Vscan Service General and Scan Engine Properties

To Display all vscan service general properties and scan engine
properties, enter

# vscanadm show

EXIT STATUS

The following exit values are returned:

0
Successful completion.

non-zero
An error occurred.

ATTRIBUTES

NOTES

All users are permitted to use vscanadm to view vscan properties and
statistics. To set property values or reset statistics, the following
authorizations are required:

solaris.smf.value.vscan

change the property values or reset statistics

solaris.manage.vscan

refresh the service to apply property value changes

To add or remove properties (add-engine, remove-engine) the following
authorizations are required:

solaris.smf.modify.application

add or remove property group

solaris.manage.vscan

refresh the service to apply property value changes

All of these authorizations are included in the "VSCAN Management"
profile.

March 10, 2023 VSCANADM(8)