'\" te
.\" Copyright (c) 2007 Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH VSCANADM 8 "March 10, 2023"
.SH NAME
vscanadm \- vscan service configuration utility
.SH SYNOPSIS
.nf
\fBvscanadm\fR \fBset\fR \fB-p\fR \fIproperty\fR=\fIvalue\fR [\fB-p\fR \fIproperty\fR=\fIvalue\fR]...
.fi

.LP
.nf
\fBvscanadm\fR \fBget\fR [\fB-p\fR \fIproperty\fR]...
.fi

.LP
.nf
\fBvscanadm\fR \fBimport\fR \fB-p\fR \fIproperty\fR \fIfilename\fR
.fi

.LP
.nf
\fBvscanadm\fR \fBexport\fR \fB-p\fR \fIproperty\fR \fIfilename\fR
.fi

.LP
.nf
\fBvscanadm\fR \fBvalidate\fR \fB-p\fR \fIproperty\fR \fIfilename\fR
.fi

.LP
.nf
\fBvscanadm\fR \fBadd-engine\fR [\fB-p\fR \fIproperty\fR=\fIvalue\fR]... \fIengine_id\fR
.fi

.LP
.nf
\fBvscanadm\fR \fBremove-engine\fR \fIengine_id\fR
.fi

.LP
.nf
\fBvscanadm\fR \fBset-engine\fR \fB-p\fR\fIproperty\fR=\fIvalue\fR [\fB-p\fR \fIproperty\fR=\fIvalue\fR]... \fIengine_id\fR
.fi

.LP
.nf
\fBvscanadm\fR \fBget-engine\fR [\fB-p\fR \fIproperty\fR=\fIvalue\fR]... [\fIengine_id\fR]
.fi

.LP
.nf
\fBvscanadm\fR \fBshow\fR
.fi

.LP
.nf
\fBvscanadm\fR \fBstats\fR [\fB-z\fR]
.fi

.SH DESCRIPTION
The \fBvscanadm\fR command sets and displays properties of the \fBvscan\fR
service, \fBvscand\fR(8), and provides scan statistics.
.sp
.LP
File system exemption from virus scanning may be configured per file system
using the appropriate file system administrative command, for example
\fBzfs\fR(8).
.sp
.LP
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 \fBvscan\fR 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
\fIengine_id\fR. The \fIengine_id\fR is a user defined string of up to 64
bytes.
.sp
.LP
The \fBvscan\fR 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.
.SH SUBCOMMANDS
\fBvscanadm\fR recognizes the following subcommands:
.sp
.ne 2
.na
\fB\fBvscanadm set\fR \fB-p\fR \fIproperty\fR=\fIvalue\fR [\fB-p\fR
\fIproperty\fR=\fIvalue\fR]...\fR
.ad
.sp .6
.RS 4n
Sets the values of \fBvscan\fR service general properties.
.sp
.ne 2
.na
\fB\fB-p\fR \fIproperty\fR=\fIvalue\fR\fR
.ad
.RS 21n
Specifies a property value
.RE

.RE

.sp
.ne 2
.na
\fB\fBvscanadm get\fR [\fB-p\fR \fIproperty\fR]...\fR
.ad
.sp .6
.RS 4n
Displays the values of \fBvscan\fR service general properties. If no properties
are specified, all \fBvscan\fR service general properties are displayed.
.sp
.ne 2
.na
\fB\fB-p\fR \fIproperty\fR\fR
.ad
.RS 15n
Specifies a property value
.RE

.RE

.sp
.LP
The following properties are available for the \fBvscanadm set\fR and
\fBvscanadm get\fR subcommands:
.sp
.ne 2
.na
\fB\fBmax-size\fR\fR
.ad
.RS 19n
The maximum size of files that should be virus scanned. Files exceeding
\fImax-size\fR are not scanned. The \fImax-size-action\fR property determines
whether access should be allowed or denied to files that exceed \fImax-size\fR.
.sp
The value of \fImax-size\fR 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]".
.sp
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.
.sp
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.
.sp
Note that while the \fBvscan\fR service defines a maximum file size for
scanning, scan engines also typically define their own maximum file size
setting. It is recommended that \fImax-size\fR be set to a value less than or
equal to the maximum file size for the scan engine(s).
.RE

.sp
.ne 2
.na
\fB\fBmax-size-action\fR\fR
.ad
.RS 19n
Specifies whether access will be allowed or denied to files larger than
\fImax-size\fR. Files larger than \fImax-size\fR are not virus scanned. Valid
values are:
.sp
.ne 2
.na
\fBallow\fR
.ad
.RS 9n
allow access to files larger than \fImax-size\fR (no virus scan). This is the
default value.
.RE

.sp
.ne 2
.na
\fBdeny\fR
.ad
.RS 9n
deny access to files larger than \fImax-size\fR (no virus scan)
.RE

.RE

.sp
.ne 2
.na
\fB\fBvscanadm import\fR \fB-p\fR \fIproperty\fR \fIfilename\fR\fR
.ad
.sp .6
.RS 4n
Imports the property value from the specified file. The file must contain a
single line specifying the value of a single property.
.RE

.sp
.ne 2
.na
\fB\fBvscanadm export\fR \fB-p\fR \fIproperty\fR \fIfilename\fR\fR
.ad
.sp .6
.RS 4n
Exports the property value to the specified file. The file must contain a
single line specifying the value of a single property.
.RE

.sp
.ne 2
.na
\fB\fBvscanadm validate\fR \fB-p\fR \fIproperty\fR \fIfilename\fR\fR
.ad
.sp .6
.RS 4n
Validates the property value in the specified file. The file must contain a
single line specifying the value of a single property.
.RE

.sp
.LP
The following properties are available for the \fBvscanadm import\fR,
\fBvscanadm export\fR, and \fBvscanadm validate\fR subcommands:
.sp
.ne 2
.na
\fB\fBtypes\fR\fR
.ad
.RS 9n
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
\fIexpression\fR against which a file's type extension is compared. The file
type \fIexpression\fR is case insensitive and may include the "*" and "?"
wildcards. There should be no whitespace between the rule indicator and the
file type \fIexpression\fR. If a comma is included within the file type
expression, it must be escaped using a "\e" (backslash). A file type extension
does not include its preceding dot.
.sp
The rule indicator is a single character and can be one of:
.sp
.in +2
.nf
+ include file type in virus scanning
- exclude file type from virus scanning
.fi
.in -2
.sp

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 "+*".
.RE

.sp
.ne 2
.na
\fB\fBvscanadm add-engine\fR [\fB-p\fR \fIproperty\fR=\fIvalue\fR]...
\fIengine_id\fR\fR
.ad
.sp .6
.RS 4n
Adds a new scan engine identified by \fIengine_id\fR. The default values are
used for any scan engine properties that are not specified. The hostname
defaults to the \fIengine_id\fR.
.sp
.ne 2
.na
\fB\fB-p\fR \fIproperty\fR=\fIvalue\fR\fR
.ad
.RS 21n
Specifies a property value
.RE

.RE

.sp
.ne 2
.na
\fB\fBvscanadm remove-engine\fR \fIengine_id\fR\fR
.ad
.sp .6
.RS 4n
Remove scan engine identified by \fIengine_id\fR, removing all of its
configuration property values.
.RE

.sp
.ne 2
.na
\fB\fBvscanadm set-engine\fR \fB-p\fR\fIproperty\fR=\fIvalue\fR [\fB-p\fR
\fIproperty\fR=\fIvalue\fR]... \fIengine_id\fR\fR
.ad
.sp .6
.RS 4n
Creates or updates the configuration property values for the scan engine
identified by \fIengine_id\fR.
.sp
.ne 2
.na
\fB\fB-p\fR \fIproperty\fR=\fIvalue\fR\fR
.ad
.RS 21n
Specifies a property value
.RE

.RE

.sp
.ne 2
.na
\fB\fBvscanadm get-engine\fR [\fB-p\fR \fIproperty\fR=\fIvalue\fR]...
[\fIengine_id\fR]\fR
.ad
.sp .6
.RS 4n
Displays the values of the specified scan engine properties for the scan engine
identified by \fIengine_id\fR. If no \fIengine_id\fR 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 \fBvscan\fR service scan engine properties.
.sp
.ne 2
.na
\fB\fB-p\fR \fIproperty\fR=\fIvalue\fR\fR
.ad
.RS 21n
Specifies a property value
.RE

.RE

.sp
.LP
The following properties are available for the \fBvscanadm add-engine\fR,
\fBvscanadm remove-engine\fR, \fBvscanadm set-engine\fR, and \fBvscanadm
get-engine\fR subcommands:
.sp
.ne 2
.na
\fB\fBenable\fR\fR
.ad
.RS 18n
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.
.RE

.sp
.ne 2
.na
\fB\fBhost\fR\fR
.ad
.RS 18n
Hostname or \fBIPv4\fR format \fBIP\fR address of the scan engine.
.RE

.sp
.ne 2
.na
\fB\fBport\fR\fR
.ad
.RS 18n
\fBICAP\fR port number of the scan engine. The numeric value ranges from 0 to
65535. The default \fBICAP\fR port is 1344.
.RE

.sp
.ne 2
.na
\fB\fBmax-connection\fR\fR
.ad
.RS 18n
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.
.RE

.sp
.ne 2
.na
\fB\fBvscanadm show\fR\fR
.ad
.RS 23n
Displays the values of all \fBvscan\fR service general properties and scan
engine properties.
.RE

.sp
.ne 2
.na
\fB\fBvscanadm stats\fR [\fB-z\fR]\fR
.ad
.RS 23n
Displays or resets the following \fBvscan\fR service statistics:
.RS +4
.TP
.ie t \(bu
.el o
number of files scanned
.RE
.RS +4
.TP
.ie t \(bu
.el o
number of infected files
.RE
.RS +4
.TP
.ie t \(bu
.el o
number of failed scan requests
.RE
.RS +4
.TP
.ie t \(bu
.el o
scan errors (including a per scan engine error count)
.RE
.sp
.ne 2
.na
\fB\fB-z\fR\fR
.ad
.RS 6n
Resets \fBvscan\fR service statistics counters to zero
.RE

.RE

.SH EXAMPLES
\fBExample 1 \fRSetting the Maximum Size Limit
.sp
.LP
To set the maximum size limit for files to be virus scanned to 128 megabytes,
enter

.sp
.in +2
.nf
# vscanadm set -p max-size=128M
.fi
.in -2
.sp

.LP
\fBExample 2 \fRAllowing Access to Files
.sp
.LP
To allow access to files exceeding the maximum file size, enter

.sp
.in +2
.nf
# vscanadm set -p max-size-action=allow
.fi
.in -2
.sp

.LP
\fBExample 3 \fRSetting File Types
.sp
.LP
To set the types so that only files of type "odt", "exe" and "jpg" are virus
scanned, enter

.sp
.in +2
.nf
# vscanadm set -p types=+odt,+exe,+jpg,-*
.fi
.in -2
.sp

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

.sp
.in +2
.nf
# vscanadm set -p types=-doc,+*
.fi
.in -2
.sp

.LP
\fBExample 4 \fRDisplaying the File Types List
.sp
.LP
To display the file types list, enter

.sp
.in +2
.nf
# vscanadm get -p types
.fi
.in -2
.sp

.LP
\fBExample 5 \fRAdding the Scan Engine
.sp
.LP
To add the scan engine "\fBmy_eng\fR" using the default values, enter

.sp
.in +2
.nf
# vscanadm add-engine my_eng
.fi
.in -2
.sp

.LP
\fBExample 6 \fRDisabling the Scan Engine
.sp
.LP
To disable the scan engine "\fBmy_eng\fR", enter

.sp
.in +2
.nf
# vscanadm set-engine -p enable=off my_eng
.fi
.in -2
.sp

.LP
\fBExample 7 \fRDisplaying Scan Engine Properties
.sp
.LP
To display the properties of the scan engine "\fBmy_eng\fR", enter

.sp
.in +2
.nf
# vscanadm get-engine my_eng
.fi
.in -2
.sp

.LP
\fBExample 8 \fRRemoving Scan Engine
.sp
.LP
To remove the scan engine "\fBmy_eng\fR", enter

.sp
.in +2
.nf
# vscanadm remove-engine my_eng
.fi
.in -2
.sp

.LP
\fBExample 9 \fRDisplaying Vscan Service General and Scan Engine Properties
.sp
.LP
To Display all vscan service general properties and scan engine properties,
enter

.sp
.in +2
.nf
# vscanadm show
.fi
.in -2
.sp

.SH EXIT STATUS
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 12n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fBnon-zero\fR\fR
.ad
.RS 12n
An error occurred.
.RE

.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Uncommitted
_
Utility output format	Not-An-Interface
.TE

.SH SEE ALSO
.BR attributes (7),
.BR smf (7),
.BR vscand (8),
.BR zfs (8)
.SH NOTES
All users are permitted to use \fBvscanadm\fR to view \fBvscan\fR properties
and statistics. To set property values or reset statistics, the following
authorizations are required:
.sp
.ne 2
.na
\fB\fBsolaris.smf.value.vscan\fR\fR
.ad
.sp .6
.RS 4n
change the property values or reset statistics
.RE

.sp
.ne 2
.na
\fB\fBsolaris.manage.vscan\fR\fR
.ad
.sp .6
.RS 4n
refresh the service to apply property value changes
.RE

.sp
.LP
To add or remove properties (\fBadd-engine\fR, \fBremove-engine\fR) the
following authorizations are required:
.sp
.ne 2
.na
\fB\fBsolaris.smf.modify.application\fR\fR
.ad
.sp .6
.RS 4n
add or remove property group
.RE

.sp
.ne 2
.na
\fB\fBsolaris.manage.vscan\fR\fR
.ad
.sp .6
.RS 4n
refresh the service to apply property value changes
.RE

.sp
.LP
All of these authorizations are included in the "\fBVSCAN\fR Management"
profile.