VSCANADM(8) Maintenance Commands and Procedures VSCANADM(8)
vscanadm - vscan service configuration utility
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]
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.
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
To set the maximum size limit for files to be virus scanned to 128
megabytes, enter
# vscanadm set -p max-size=128M
To allow access to files exceeding the maximum file size, enter
# vscanadm set -p max-size-action=allow
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,+*
To display the file types list, enter
# vscanadm get -p types
To add the scan engine "my_eng" using the default values, enter
# vscanadm add-engine my_eng
To disable the scan engine "my_eng", enter
# vscanadm set-engine -p enable=off my_eng
To display the properties of the scan engine "my_eng", enter
# vscanadm get-engine my_eng
To remove the scan engine "my_eng", enter
# vscanadm remove-engine my_eng
To Display all vscan service general properties and scan engine
properties, enter
# vscanadm show
The following exit values are returned:
0
Successful completion.
non-zero
An error occurred.
See attributes(7) for descriptions of the following attributes:
+----------------------+------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+----------------------+------------------+
|Interface Stability | Uncommitted |
+----------------------+------------------+
|Utility output format | Not-An-Interface |
+----------------------+------------------+
attributes(7), smf(7), vscand(8), zfs(8)
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)
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
See attributes(7) for descriptions of the following attributes:
+----------------------+------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+----------------------+------------------+
|Interface Stability | Uncommitted |
+----------------------+------------------+
|Utility output format | Not-An-Interface |
+----------------------+------------------+
SEE ALSO
attributes(7), smf(7), vscand(8), zfs(8)
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)