ClamAV For Windows SigUI Manual

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 23

Signature conﬁguration UI

User Manual

Contents

1 Overview 3

1.1 Features .............................. 3

1.2 Using SigUI ............................ 4

1.2.1 Launching the application ................ 4

1.2.2 How it works ....................... 4

2 Usage examples 5

2.1 Conﬁguring a proxy ........................ 5

2.2 Choosing a mirror ......................... 6

2.3 Deploying custom signature updates .............. 6

2.3.1 Deploying your own signatures from a webserver .... 7

2.3.2 Deploying your own signatures from a network share . 7

2.3.3 Deploying third-party signatures ............. 8

2.3.4

Manually copying custom signatures to database directory

2.3.5 Removing signature ﬁles ................. 9

2.3.6

Automating signature and conﬁguration ﬁle deploy-

ments on a network .................... 10

2.4 Setting up a local mirror ..................... 11

3 User interface 13

3.1 Updater conﬁguration ...................... 13

3.1.1 Proxy settings ....................... 13

3.1.2 Signature sources ..................... 13

3.1.3 Saving conﬁguration and testing ............. 14

3.2 Local signature management ................... 14

3.3 Run freshclam to test conﬁguration ............... 15

3.4 Custom URLs ........................... 15

3.5 Reloading the databases ..................... 17

4 Copyright and License 19

2Contents

Glossary 21

ClamAV for Windows - Signature conﬁguration UI - User Manual,

Authors: Török Edvin

This document is distributed under the terms of the GNU General Public

License v2.

Clam AntiVirus is free software; you can redistribute it and/or modify it

under the terms of the GNU General Public License as published by the

Free Software Foundation; version 2 of the License.

This program is distributed in the hope that it will be useful, but

WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along

with this program; if not, write to the Free Software Foundation, Inc., 51

Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

ClamAV and Clam AntiVirus are trademarks of Sourceﬁre, Inc.

CHAPTER 1

Overview

ClamAV

allows users to deploy and use their own (or third party) virus

signatures in addition to the oﬃcial virus signatures. The virus signature

database updater (

freshclam

) can also be adapted to the user’s environment.

This is usually done by editing the conﬁguration ﬁle

freshclam.conf

and copying the custom signatures to the database directory.

However

ClamAV for Windows

protects the database directory against

changes, even if those changes are attempted by a user with Administra-

tor privileges. A new tool is needed to make these changes:

Signature

conﬁguration UI (SigUI).

1.1. Features

Using SigUI an Administrator can:

•Conﬁgure freshclam to use a proxy

•Conﬁgure which mirror freshclam should use

•Conﬁgure updates of custom signatures by freshclam

•

Manually copy virus signature databases to

ClamAV

’s database direc-

tory

•Deploy an existing freshclam.conf 1to multiple machines

1created using SigUI

41.2. Using SigUI

1.2. Using SigUI

1.2.1. Launching the application

The application can be launched from the Start Menu: Start

→

All Programs

→ClamAV for Windows →SigUI

Or you can navigate to the installation directory of

ClamAV for Win-

dows1, and from the clamav subfolder launch sigui.exe:

In either case you must run this program with administrative privileges. On

Windows Vista and later you will get the UAC popup to grant Administrator

privileges to the application

. On earlier versions you will need to login as

Administrator.

1.2.2. How it works

When changing

freshclam

settings via the UI, it ﬁrst veriﬁes that the settings

are syntactically correct, and saves them in freshclam.conf.

When installing custom signatures,

SigUI

veriﬁes that

ClamAV

can suc-

cessfully load the databases, and install only those that are successfully

loaded.

Once the databases are successfully installed, a reload is queued. ClamAV

for Windows will reload the databases the next time the system is idle. SigUI

will show a notiﬁcation when the reload happens.

1C:\Program Files\ClamAV for Windows by default

If you are running as a user that has Administrator privileges, this is a simple "I

Allow/Continue" style popup, otherwise it asks you for a login and password of a user with

Administrator privileges

CHAPTER 2

Usage examples

2.1. Conﬁguring a proxy

Freshclam

by default attemps to connect to the Internet directly. If you can

only access the Internet by using a proxy, then you should conﬁgure the proxy

using SigUI.

If you have already conﬁgured a system wide proxy setting, then easiest

is to just press the Retrieve system proxy settings button on the Updater

conﬁguration tab. This will retrieve the proxy settings from Internet Explorer,

and display them in the Proxy settings section. If the settings are correct,

click Save settings.

You can also manually input the proxy settings:

•Tick the Proxy required for Internet access checkbox

•

Set the proxy server and port in the Proxy server: and Proxy port:

ﬁelds

•

If the proxy requires a username and password, then tick the Authenti-

cation required checkbox

–Enter the username in the Proxy username: ﬁeld

–Enter the password in the Proxy password: ﬁeld 1

•Check that the settings are correct

•Click Save settings

To test whether the proxy settings work, click Run freshclam to test

conﬁguration. This will run

freshclam

, and display an error if it failed to

connect through the proxy. See Section 3.3 for details.

1Note that the password will be saved as cleartext in freshclam.conf

62.2. Choosing a mirror

2.2. Choosing a mirror

Freshclam

by default uses the

db.local.win.clamav.net

mirror. Although

this works well most of the time, you can get better download speeds by using

a mirror from your country:

•Open SigUI

•Open the Download Oﬃcial Signatures from mirror dropdown 1

•

Mirrors are of the form

db.XY.clamav.net

, where XY is your two-letter

country-code

•Select the mirror corresponding to your country

•Click Save settings

You can also enter the hostname of the mirror you wish to use, instead of

choosing one from the dropdown. This mirror can be a server on your own

network too. See Section 2.4.

2.3. Deploying custom signature updates

In addition to the oﬃcial virus signatures, you can use your own signatures, or

signatures provided by third-parties. To deploy them you have these choices:

•Put your custom signatures on your own webserver. See Section 2.3.1

•Put your custom signatures on a network share. See Section 2.3.2

•

Manually copy your custom signatures each time you change them. See

Section 2.3.4

•

Write and deploy a script that copies the signatures to a local drive,

and runs SigUI in command-line mode. See Section 2.3.6

A reload of the signatures is queued once the signatures are installed. See

Section 3.5.

1On the Updater conﬁguration tab, in the Signature sources section

Chapter 2. Usage examples 7

2.3.1. Deploying your own signatures from a webserver

If you have written your own signatures and want to deploy them to multiple

ClamAV for Windows

installations on your network, then the easiest is

to put the signatures on your webserver (in your LAN).

The custom signature can be in any format that

ClamAV

understands.

See

http://www.clamav.net/doc/latest/signatures.pdf

section 3 "Sig-

nature formats" for details about the format. All the signature ﬁles, except

CVD, are ASCII ﬁles. Both Unix (LF) and Windows-style (CR+LF) line-

endings are accepted. CVD ﬁles are binary ﬁles though, so you should not

modify them. The format of signatures is determined based on the database

extension (in a case insensitive manner), so you must make sure to preserve

the ﬁle’s contents and extension when copying it. (You can safely rename the

ﬁle, as long as you preserve the extension).

Since these ﬁles are not digitally signed

, it is your responsibility to ensure

that the signature ﬁles are not altered (by malware, etc.).

Deploying a new signature ﬁle is easy:

•Copy the signature to your webserver, at a location of your choice

•Open SigUI

•Click the Add button next to the Custom signature URLs section

•Enter the full URL to your new signature ﬁle

•Click OK.

•Click Save settings

•See Section 3.4 for details

•

You can repeat this operation on each machine that has

ClamAV for Win-

dows installed, or you can automate it, see Section 2.3.6

2.3.2. Deploying your own signatures from a network

This is similar to downloading a signature ﬁle from a webserver, see Sec-

tion 2.3.1. Except you have to add an UNC path instead of an

http://

URL.

1Oﬃcial CVD ﬁles are digitally signed

82.3. Deploying custom signature updates

However

ClamAV for Windows

requires this UNC path to be readable

by the SYSTEM account. Usually network shares, and network mapped

drives are not accessible to this user. If you have made them accessible (it is

out of scope for this document to discuss how), then you can of course use

them in SigUI.

2.3.3. Deploying third-party signatures

If you want to deploy third-party signatures that are not in

CVD

format

, you

can do so with some additional steps:

•Download the third-party signatures to your server

•

Check their integrity by comparing against the third-party supplied

checksum and digital signatures. There usually are scripts to accomplish

this

•Copy the signatures to your webserver, at a location of your choice

•

Make sure you preserve the extension of the ﬁles, as the signature format

is determined based on the extension

•

Add the full URL path to these signatures to

freshclam.conf

using

SigUI. See Section 3.4

Note that if you add third-party signatures memory usage will increase

(depending on the complexity and size of the signatures), and performance

may be diﬀerent.

Note that the downloaded signature ﬁles will all be placed in the same

directory. Hence you must make sure you don’t have two URLs that, when

downloaded, have the same ﬁlename. The UI will warn you if you try to do

that2.

2.3.4. Manually copying custom signatures to database

directory

•ClamAV for Windows

will load them the next time it updates the

database (usually once ah hour)

•

If there are signatures that fail veriﬁcation an error message will be

shown, with details on why the signatures failed to load.

2.3.5. Removing signature ﬁles

If you want to remove one of your signatures, you can select the ﬁle in the

Installed signatures list, and click Delete. This will erase the ﬁle from the disk!

Note that you can delete the ﬁles automatically downloaded by

freshclam

too, but they will just reappear at the next update. The only ﬁle you can’t

delete is daily.cvd and daily.cld. The presence of one these ﬁles is essential to

the proper operation of the ClamAV engine.

Or .cld once they are updated. CVD ﬁles change into CLD ﬁles upon an update. Of

course if the updater didn’t run yet you won’t see any ﬁles there

2clamav\staging_dir subdirectory

3Using libclamav.dll only, they are not loaded in the realtime engine

10 2.3. Deploying custom signature updates

2.3.6. Automating signature and conﬁguration ﬁle de-

ployments on a network

The graphical mode of SigUI is useful for making local changes to

freshclam.conf

and the database directory. However if you want to automate the process

(call it from a script), there is a commandline interface too:

•

You must run it as Administrator user. Otherwise you get the UAC

popup, which is not what you want in a script.

•If you want to copy signatures to the database directory:

–

Create a ﬁle

signatureslist

with the full path to the signatures

you want to install, one on a line. Don’t quote or escape the

ﬁlenames, just write them as is.

–Run:

"C :\ Pr ogram Files \ ClamAV for Windows \ clamav \ SigUI . exe

" -i <signatureslist

–

Another alternative is to pipe it the output of another program

echo ’< databasepath >’ | "C :\ Pr ogram Files \ ClamAV for

Wi ndow s \ clama v \ Si gUI . exe " -i

–

SigUI will test each database by loading them, and prints progress

messages to the standard output.

–

SigUI will print error messages on failed database loads to the

standard error

–

The exitcode will be 0 if all signatures were successfully installed,

and nonzero if some signatures failed to install

Note that using

freshclam

’s support for custom signature URLs is

usually a better solution, you will only need to deploy the modiﬁed

freshclam.conf.

•Deploying a modiﬁed freshclam.conf:

–Create a freshclam.conf on one machine with SigUI

–Test it, see Section 3.3

1Interactively entering the ﬁlenames from the commandprompt won’t work

Chapter 2. Usage examples 11

–

Write a script to automatically invoke

SigUI.exe

on each ma-

chine on your network (for example using a logon script, or a

msi

installer)

–Have it execute this command:

"C :\ Pr ogram Files \ ClamAV for Windows \ clamav \ SigUI . exe

" -w <new \ _fre shcl am . conf

–Alternatively you can pipe it the freshclam.conf:

som ec om man d | " C :\ P ro gram Fi les \ Cla mAV for Wi nd ows \

clamav \ SigUI . exe " -w

–

SigUI will test the conﬁg ﬁle for syntactic correctness, and install

it if it is valid

2.4. Setting up a local mirror

If you have a lot of ClamAV installations on your local network, then you

can setup

freshclam

as described in the answer for I’m running ClamAV

on a lot of clients on my local network at

http://www.clamav.net/lang/

en/support/faq/faq-cvd/

. Once you’ve setup the local mirror you can

conﬁgure it:

•Open SigUI

•

Enter the hostname, or IP address of your local mirror in the Download

oﬃcial signatures from mirror: ﬁeld

•Click Save settings

•Click Run freshclam to test conﬁguration. See Section 3.3

Another option is to setup a caching proxy, and set ClamAV to use that.

See Section 2.1.

12 2.4. Setting up a local mirror

CHAPTER 3

User interface

3.1. Updater conﬁguration

When you open SigUI the Updater conﬁguration tab is open, see Figure 3.1.

Figure 3.1: Updater conﬁguration

It has 2 sections:

3.1.1. Proxy settings

If Proxy required for Internet access

is not ticked, then

freshclam

will

connect directly to the internet.

If it is ticked, then the server

and port ﬁelds, and Authentication

required checkbox will be enabled.

If the Authentication required

checkbox is ticked the username and

password ﬁelds will be enabled too.

The Retrieve system proxy set-

tings will attempt to retrieve the

proxy settings from Internet Ex-

plorer, and ﬁll the above ﬁelds.

See Section 2.1 for an example.

3.1.2. Signature sources

Here you can conﬁgure what databases

will

freshclam

automatically down-

load.

14 3.2. Local signature management

Download Oﬃcial Signatures from

mirror allows you to choose the mir-

ror that

freshclam

will use to download the virus databases. You can either

enter a custom hostname, or select one from the list (preferably the one that

matches your countrycode). See Section 2.2 for an example.

Oﬃcial bytecode signatures is by default enabled. If you want to disable

it, untick it. But you must be aware that you will miss some detections, or

even bugﬁxes.

Custom signature URLs is a list of custom URLs that

freshclam

will

download and install as new virus signature databases. You can use the Add

and Remove buttons to manage the list. The list accepts

http://

URLs, or

UNC pathes. See Section 2.3 for detailed examples.

3.1.3. Saving conﬁguration and testing

Pressing the Save settings will validate all the ﬁelds on this tab, and save

the settings to

freshclam.conf

. If there is anything wrong an error message

will be shown.

Pressing the Run freshclam to test conﬁguration will test whether the new

freshclam.conf

works as expected. If this results in error you should ﬁx it,

otherwise your custom databases won’t be used.1

3.2. Local signature management

This tab allows you to manage the signatures installed in the database

directory, see Figure 3.2.

There upper section, New signatures shows the signatures you are about

to install, and the bottom section, Installed signatures shows the already

installed signatures. You can manage the top list using the Add and Remove

button (Add launches a standard Open ﬁle dialog).

The bottom list is managed by SigUI and

freshclam

. You can press

Verify and Install signatures to validate and copy the signatures from the

list above to the one below. Signatures are only copied after they have been

veriﬁed as valid, an error is shown for malformed signatures. See Section 2.3.4

for an example.

The oﬃcial ones should still be downloaded correctly even in case of errors, unless

freshclam.conf is very broken

Chapter 3. User interface 15

Figure 3.2: Local signature management

The Delete button will delete the

actual signatures ﬁles from disk, it

should be used only if you know

what you are doing (a conﬁrmation

message is shown prior to delete of

course).

3.3. Run freshclam to

test conﬁguration

Pressing this button will launch

freshclam

, and opens a window to

show its output, see Figure 3.3.

The output shows the progress

of the update, and any error mes-

sages from

freshclam

. It is rec-

ommended that once you change

freshclam.conf

, by clicking Save

settings, to test it by clicking on Run

freshclam to test conﬁguration.

The window has a button to force-

fully terminate

freshclam

, but this

should only be used if for some rea-

son it hangs. Note that by default

the timeout for connecting to a re-

mote server is 30 seconds, so you should wait at least 30 seconds before

terminating it.

Figure 3.3: SigUI: Freshclam output

window

Once

freshclam

ﬁnishes the but-

ton changes to a Close window but-

ton, that can be safely pressed to

dismiss the window.

3.4. Custom URLs

The Custom signature URLs section

on the Updater conﬁguration page

allows you to add custom URLs.

16 3.4. Custom URLs

Freshclam

will automatically

download these each time it updates

the oﬃcial signatures (usually once

an hour). If your webserver supports

If-Modified-Since

headers, it will only download the new database if it is

newer than the already installed one.

Digital signatures are checked only for

CVD

signatures

. Freshclam auto-

matically tests all signatures (for syntactic correctness) after downloading,

but before installing them. If a signature ﬁle is malformed it is not installed

and an error is logged.

Usage:

•Click Add to add a new URL, press OK when done

•

If the URL is not in the correct format, an error message is shown.

Correct the URL and press OK again.

•The new URL shows up in the Custom signature URLs section

•Add as many URLs as needed

•

You can remove an URL by clicking the Remove button.

WARNING

If the database was already downloaded it won’t remove the downloaded

signature ﬁle from the disk. See Section 2.3.5 on how to do that.

•Check that you entered the correct URLs.

•Click Save settings.

•

Click Run freshclam to test conﬁguration to make sure freshclam is

able to correctly download the signatures. Freshclam will only install

signatures that are in the syntactically correct. See Section 3.3

Note that the downloaded signature ﬁles will all be placed in the same

directory. Hence you must make sure you don’t have two URLs that, when

downloaded, have the same ﬁlename. The UI will warn you if you try to do

that. 2.

1because they are the only ones that contain such signatures

2the two URLs with same ﬁlenames will just keep overwriting the same ﬁle

Chapter 3. User interface 17

3.5. Reloading the databases

A database reload is automatically queued in the following situations:

•

You click Run freshclam to test conﬁguration, after freshclam ﬁnishes

and you close the window

•You install new databases by clicking on Verify and Install signatures

•You remove a database by using the Delete button

The reload will happen the next time the system is idle (or immediately

if already idle).

18 3.5. Reloading the databases

CHAPTER 4

The Signature conﬁguration UI is released under the GNU General Public

License version 2.

This program is free software; you can redistribute it and/or modify

it under the terms of the GNU General Public License version 2 as

published by the Free Software Foundation.

This program is distributed in the hope that it will be useful,

but WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

GNU General Public License for more details.

You should have received a copy of the GNU General Public License

along with this program; if not, write to the Free Software

Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,

MA 02110-1301, USA.

Glossary

ClamAV

Clam AntiVirus engine, see

http://www.clamav.net

.3,4,7–9,

CVD

ClamAV Virus Database. A ﬁle that contains multiple signature types,

and a digital signature. This is the format in which the oﬃcial signatures

are distributed. 7,8,16

daily.cld Adaily.cvd, after freshclam updated it. 9

daily.cvd

An important database ﬁle for

ClamAV

. Contains often updated

virus signatures, ﬁle type deﬁnitions, engine conﬁguration, and whitelists.

9,21

db.local.win.clamav.net

db.local.win.clamav.net is a round robin record

that tries to equally balance the traﬃc between the best database

mirrors.. 6

freshclam ClamAV

’s signature databases updater application. 3–6,9–11,

13–16,21

freshclam.conf The conﬁguration ﬁle for freshclam.3–5,8,10,14,15

hostname DNS name of a server. 6

mirror

A server holding an exact copy of the original server, for better load

balancing and bandwidth purposes.. 6,14

SigUI

ClamAV for Windows - Signature Conﬁguration User Interface. The

application documented in this manual. 8,10

SYSTEM account

A highly privileged account. This is the account used

by system services. You cannot login as SYSTEM. 8

22 Glossary

UAC

User Account Control, a security infrastructure introduced in Windows

Vista. 10

UNC path

Uniform Naming Convention path. A path of the form

\\ComputerName

\\SharedFolder \\Resource

, or a long UNC path starting with

\\?\

7,8,14

ClamAV For Windows SigUI Manual

Navigation menu

Versions of this User Manual:

Views

Navigation