deleted file mode 100644

@@ -1,105 +0,0 @@

-# Configuration

-

-Before proceeding with the steps below, you should run the ’clamconf’ command, which gives important information about your ClamAV configuration. See section [5.8](#sec:clamconf) for more details.

-

-## clamd

-

-Before you start using the daemon you have to edit the configuration file (in other case `clamd` won’t run):

-

-```bash

-    $ clamd

-    ERROR: Please edit the example config file /etc/clamd.conf.

-```

-

-This shows the location of the default configuration file. The format and options of this file are fully described in the *clamd.conf(5)* manual. The config file is well commented and configuration should be straightforward.

-

-### On-access scanning

-

-One of the interesting features of `clamd` is on-access scanning based on fanotify, included in Linux since kernel 2.6.36. **This is not required to run clamd**. At the moment the fanotify header is only available for Linux.

-

-Configure on-access scanning in `clamd.conf` and read the [on-access](Usage.md#On-access-Scanning) section for on-access scanning usage.

-

-## clamav-milter

-

-ClamAV (v0.95) includes a new, redesigned clamav-milter. The most notable difference is that the internal mode has been dropped and now a working clamd companion is required. The second important difference is that now the milter has got its own configuration and log files.

-

-To compile ClamAV with the clamav-milter just run `./configure --enable-milter` and make as usual. In order to use the `–enable-milter` option with `configure`, your system MUST have the milter library installed. If you use the `–enable-milter` option without the library being installed, you will most likely see output like this during ’configure’:

-

-```bash

-        checking for libiconv_open in -liconv... no

-        checking for iconv... yes

-        checking whether in_port_t is defined... yes

-        checking for in_addr_t definition... yes

-        checking for mi_stop in -lmilter... no

-        checking for library containing strlcpy... no

-        checking for mi_stop in -lmilter... no

-        configure: error: Cannot find libmilter

-```

-

-At which point the ’configure’ script will stop processing.

-

-Please consult your MTA’s manual on how to connect ClamAV with the milter.

-

-## Testing

-

-Try to scan recursively the source directory:

-

-```bash

-    $ clamscan -r -l scan.txt clamav-x.yz

-```

-

-It should find some test files in the clamav-x.yz/test directory. The scan result will be saved in the `scan.txt` log file \[7\]. To test `clamd`, start it and use `clamdscan` (or instead connect directly to its socket and run the SCAN command):

-

-```bash

-    $ clamdscan -l scan.txt clamav-x.yz

-```

-

-Please note that the scanned files must be accessible by the user running `clamd` or you will get an error.

-

-## Setting up auto-updating

-

-`freshclam` is the automatic database update tool for Clam AntiVirus. It can work in two modes:

-

-- interactive - on demand from command line

-- daemon - silently in the background

-

-`freshclam` is advanced tool: it supports scripted updates (instead of transferring the whole CVD file at each update it only transfers the differences between the latest and the current database via a special script), database version checks through DNS, proxy servers (with authentication), digital signatures and various error scenarios. **Quick test: run freshclam (as superuser) with no parameters and check the output.** If everything is OK you may create the log file in /var/log (owned by *clamav* or another user `freshclam` will be running as):

-

-```bash

-    # touch /var/log/freshclam.log

-    # chmod 600 /var/log/freshclam.log

-    # chown clamav /var/log/freshclam.log

-```

-

-Now you *should* edit the configuration file `freshclam.conf` and point the *UpdateLogFile* directive to the log file. Finally, to run `freshclam` in the daemon mode, execute:

-

-```bash

-    # freshclam -d

-```

-

-The other way is to use the *cron* daemon. You have to add the following line to the crontab of **root** or **clamav** user:

-

-```cron

-N * * * *   /usr/local/bin/freshclam --quiet

-```

-

-to check for a new database every hour. **N should be a number between 3 and 57 of your choice. Please don’t choose any multiple of 10, because there are already too many clients using those time slots.** Proxy settings are only configurable via the configuration file and `freshclam` will require strict permission settings for the config file when `HTTPProxyPassword` is turned on.

-

-```bash

-    HTTPProxyServer myproxyserver.com

-    HTTPProxyPort 1234

-    HTTPProxyUsername myusername

-    HTTPProxyPassword mypass

-```

-

-### Closest mirrors

-

-The `DatabaseMirror` directive in the config file specifies the database server `freshclam` will attempt (up to `MaxAttempts` times) to download the database from. The default database mirror is [database.clamav.net](database.clamav.net) but multiple directives are allowed. In order to download the database from the closest mirror you should configure `freshclam` to use [db.xx.clamav.net](db.xx.clamav.net) where xx represents your country code. For example, if your server is in "Ascension Island" you should have the following lines included in `freshclam.conf`:

-

-```bash

-    DNSDatabaseInfo current.cvd.clamav.net

-    DatabaseMirror db.ac.clamav.net

-    DatabaseMirror database.clamav.net

-```

-

-The second entry acts as a fallback in case the connection to the first mirror fails for some reason. The full list of two-letters country codes is available at <http://www.iana.org/cctld/cctld-whois.htm>

@@ -1,215 +1,33 @@

 # Usage

-## Clam daemon

+This User Guide presents an overview of the various ways that *libclamav* can be used through the tools provided by ClamAV. To learn more about how to better use each facet of ClamAV that interests you, please follow the links provided.

-`clamd` is a multi-threaded daemon that uses *libclamav* to scan files for viruses. It may work in one or both modes listening on:

+## Daemon

-- Unix (local) socket

-- TCP socket

+The ClamAV Daemon, or [`clamd`](Usage/Scanning.md#clamd), is a multi-threaded daemon that uses *libclamav* to [scan files for viruses](Usage/Scanning.md). ClamAV provides a number of tools which interface with this daemon. They are, as follows:

-The daemon is fully configurable via the `clamd.conf` file \[8\]. `clamd` recognizes the following commands:

+  - [`clamdscan`](Usage/Scanning.md#clamdscan) - a simple scanning client

+  - [`on-access scanning`](Usage/Scanning.md#On-access-scanning) - a special `clamd` thread for real-time protection

+  - [`clamdtop`](Usage/Scanning.md#clamdtop) - a resource monitoring interface for `clamd`

-- **PING**

-    Check the daemon’s state (should reply with "PONG").

-- **VERSION**

-    Print program and database versions.

-- **RELOAD**

-    Reload the databases.

-- **SHUTDOWN**

-    Perform a clean exit.

-- **SCAN file/directory**

-    Scan file or directory (recursively) with archive support enabled (a full path is required).

-- **RAWSCAN file/directory**

-    Scan file or directory (recursively) with archive and special file support disabled (a full path is required).

-- **CONTSCAN file/directory**

-    Scan file or directory (recursively) with archive support enabled and don’t stop the scanning when a virus is found.

-- **MULTISCAN file/directory**

-    Scan file in a standard way or scan directory (recursively) using multiple threads (to make the scanning faster on SMP machines).

-- **ALLMATCHSCAN file/directory**

-    ALLMATCHSCAN works just like SCAN except that it sets a mode where, after finding a virus within a file, continues scanning for additional viruses.

-- **INSTREAM**

-    *It is mandatory to prefix this command with **n** or **z**.* Scan a stream of data. The stream is sent to clamd in chunks, after INSTREAM, on the same socket on which the command was sent. This avoids the overhead of establishing new TCP connections and problems with NAT. The format of the chunk is: `<length><data>` where `<length>` is the size of the following data in bytes expressed as a 4 byte unsigned integer in network byte order and `<data>` is the actual chunk. Streaming is terminated by sending a zero-length chunk. Note: do not exceed StreamMaxLength as defined in clamd.conf, otherwise clamd will reply with *INSTREAM size limit exceeded* and close the connection.

-- **FILDES**

-    *It is mandatory to newline terminate this command, or prefix with **n** or **z**. This command only works on UNIX domain sockets.* Scan a file descriptor. After issuing a FILDES command a subsequent rfc2292/bsd4.4 style packet (with at least one dummy character) is sent to clamd carrying the file descriptor to be scanned inside the ancillary data. Alternatively the file descriptor may be sent in the same packet, including the extra character.

-- **STATS**

-    *It is mandatory to newline terminate this command, or prefix with **n** or **z**, it is recommended to only use the **z** prefix.* On this command clamd provides statistics about the scan queue, contents of scan queue, and memory usage. The exact reply format is subject to changes in future releases.

-- **IDSESSION, END**

-    *It is mandatory to prefix this command with **n** or **z**, also all commands inside **IDSESSION** must be prefixed.* Start/end a clamd session. Within a session multiple SCAN, INSTREAM, FILDES, VERSION, STATS commands can be sent on the same socket without opening new connections. Replies from clamd will be in the form `<id>: <response>` where `<id>` is the request number (in ASCII, starting from 1) and `<response>` is the usual clamd reply. The reply lines have the same delimiter as the corresponding command had. Clamd will process the commands asynchronously, and reply as soon as it has finished processing. Clamd requires clients to read all the replies it sent, before sending more commands to prevent send() deadlocks. The recommended way to implement a client that uses IDSESSION is with non-blocking sockets, and a select()/poll() loop: whenever send would block, sleep in select/poll until either you can write more data, or read more replies. *Note that using non-blocking sockets without the select/poll loop and alternating recv()/send() doesn’t comply with clamd’s requirements.* If clamd detects that a client has deadlocked, it will close the connection. Note that clamd may close an IDSESSION connection too if the client doesn’t follow the protocol’s requirements.

-- **STREAM** (deprecated, use **INSTREAM** instead)

-    Scan stream: clamd will return a new port number you should connect to and send data to scan.

+## Scanner

-It’s recommended to prefix clamd commands with the letter **z** (eg. zSCAN) to indicate that the command will be delimited by a NULL character and that clamd should continue reading command data until a NULL character is read. The null delimiter assures that the complete command and its entire argument will be processed as a single command. Alternatively commands may be prefixed with the letter **n** (e.g. nSCAN) to use a newline character as the delimiter. Clamd replies will honour the requested terminator in turn. If clamd doesn’t recognize the command, or the command doesn’t follow the requirements specified below, it will reply with an error message, and close the connection. Clamd can handle the following signals:

+ClamAV also provides a command-line tool for [simple scanning](Usage/Scanning.md) tasks with *libclamav* called [`clamscan`](Usage/Scanning,md#clamscan). Unlike the daemon, `clamscan` is not a persistent process and is best suited for use cases where one-time scanning with minimal setup is needed.

-- **SIGTERM** - perform a clean exit

-- **SIGHUP** - reopen the log file

-- **SIGUSR2** - reload the database

+## Signature Testing and Management

-Clamd should not be started in the background using the shell operator `&` or external tools. Instead, you should run and wait for clamd to load the database and daemonize itself. After that, clamd is instantly ready to accept connections and perform file scanning.

+A number of tools allow for [testing and management of signatures](Usage/SignatureManagement.md). Of note are the following:

-## Clam**d**scan

+  - [`clambc`](Usage/SignatureManagement.md#clambc) - specifically for testing bytecode

+  - [`sigtool`](Usage/SignatureManagement.md#sigtool) - for general signature testing and analysis

+  - [`freshclam`](Usage/SignatureManagement.md#freshclam) - used to update signature database sets to the latest version

-`clamdscan` is a simple `clamd` client. In many cases you can use it as a `clamscan` replacement however you must remember that:

-- it only depends on `clamd`

-- although it accepts the same command line options as `clamscan` most of them are ignored because they must be enabled directly in `clamd`, i.e. `clamd.conf`

-- in TCP mode scanned files must be accessible for `clamd`, if you enabled LocalSocket in clamd.conf then clamdscan will try to workaround this limitation by using FILDES

+## Configuration

-## On-access Scanning

+The more complex tools ClamAV provides each require some degree of [configuration](Usage/Configuration.md). ClamAV supplies two examples configuration files:

-There is a special thread in `clamd` that performs on-access scanning under Linux and shares internal virus database with the daemon. By default, this thread will only notify you when potential threats are discovered. If you turn on prevention via `clamd.conf` then **you must follow some important rules when using it:**

+  - [`clamd.conf`](Usage/Configuration.md#clamd-configuration) - for configuring the behaviour of the ClamAV Daemon `clamd` and associated tools

+  - [`freschclam.conf`](Usage/Configuration.md#freshclam-configuration) - for configuring the behaviour of the signature database update tool, `freshclam`

-- Always stop the daemon cleanly - using the SHUTDOWN command or the SIGTERM signal. In other case you can lose access to protected files until the system is restarted.

-- Never protect the directory your mail-scanner software uses for attachment unpacking. Access to all infected files will be automatically blocked and the scanner (including `clamd`\!) will not be able to detect any viruses. In the result **all infected mails may be delivered.**

-- Watch your entire filesystem only using the `clamd.conf` OnAccessMountPath option. While this will disable on-access prevention, it will avoid potential system lockups caused by fanotify’s blocking functionality.

-- Using the On-Access Scanner to watch a virtual filesystem will result in undefined behaviour.

-

-For more configuration options, type ’man clamd.conf’ or reference the example clamd.conf. And for additional details on how to use this feature, please reference the [OnAccess usage manual](OnAccess.md).

-

-## Clamdtop

-

-`clamdtop` is a tool to monitor one or multiple instances of clamd. It has a (color) ncurses interface, that shows the jobs in clamd’s queue, memory usage, and information about the loaded signature database. You can specify on the command-line to which clamd(s) it should connect to. By default it will attempt to connect to the local clamd as defined in clamd.conf.

-

-For more detailed help, type ’man clamdtop’ or ’clamdtop –help’.

-

-## Clamscan

-

-`clamscan` is ClamAV’s command line virus scanner. It can be used to scan files and/or directories for viruses. In order for clamscan to work proper, the ClamAV virus database files must be installed on the system you are using clamscan on.

-

-The general usage of clamscan is: clamscan \[options\]

-\[file/directory/-\]

-

-For more detailed help, type ’man clamscan’ or ’clamscan –help’.

-

-## ClamBC

-

-`clambc` is Clam Anti-Virus’ bytecode testing tool. It can be used to test files which contain bytecode. For more detailed help, type ’man clambc’ or ’clambc –help’.

-

-## Freshclam

-

-`freshclam` is ClamAV’s virus database update tool and reads it’s configuration from the file ’freshclam.conf’ (this may be overridden by command line options). Freshclam’s default behavior is to attempt to update databases that are paired with downloaded cdiffs. Potentially corrupted databases are not updated and are automatically fully replaced after several failed attempts unless otherwise specified.

-

-Here is a sample usage including cdiffs:

-

-```bash

-$ freshclam

-

-ClamAV update process started at Mon Oct  7 08:15:10 2013

-main.cld is up to date (version: 55, sigs: 2424225, f-level: 60, builder: neo)

-Downloading daily-17945.cdiff [100%]

-Downloading daily-17946.cdiff [100%]

-Downloading daily-17947.cdiff [100%]

-daily.cld updated (version: 17947, sigs: 406951, f-level: 63, builder: neo)

-Downloading bytecode-227.cdiff [100%]

-Downloading bytecode-228.cdiff [100%]

-bytecode.cld updated (version: 228, sigs: 43, f-level: 63, builder: neo)

-Database updated (2831219 signatures) from database.clamav.net (IP: 64.6.100.177)

-```

-

-For more detailed help, type ’man clamscan’ or ’clamscan –help’.

-

-## Clamconf

-

-`clamconf` is the Clam Anti-Virus configuration utility. It is used for displaying values of configurations options in ClamAV, which will show the contents of clamd.conf (or tell you if it is not properly configured), the contents of freshclam.conf, and display information about software settings, database, platform, and build information. Here is a sample clamconf output:

-

-```bash

-$ clamconf

-

-Checking configuration files in /etc/clamav

-

-Config file: clamd.conf

-ERROR: Please edit the example config file /etc/clamav/clamd.conf

-

-Config file: freshclam.conf

-ERROR: Please edit the example config file /etc/clamav/freshclam.conf

-

-clamav-milter.conf not found

-

-Software settings

-Version: 0.98.2

-Optional features supported: MEMPOOL IPv6 AUTOIT_EA06 BZIP2 RAR JIT

-

-Database information

-Database directory: /xclam/gcc/release/share/clamav

-WARNING: freshclam.conf and clamd.conf point to different database directories

-print_dbs: Can't open directory /xclam/gcc/release/share/clamav

-

-Platform information

-uname: Linux 3.5.0-44-generic #67~precise1-Ubuntu SMP Wed Nov 13 16:20:03 UTC 2013 i686

-OS: linux-gnu, ARCH: i386, CPU: i686

-Full OS version: Ubuntu 12.04.3 LTS

-zlib version: 1.2.3.4 (1.2.3.4), compile flags: 55

-Triple: i386-pc-linux-gnu

-CPU: i686, Little-endian

-platform id: 0x0a114d4d0404060401040604

-

-Build information

-GNU C: 4.6.4 (4.6.4)

-GNU C++: 4.6.4 (4.6.4)

-CPPFLAGS:

-CFLAGS: -g -O0 -D_LARGEFILE_SOURCE -D_LARGEFILE64_SOURCE

-CXXFLAGS:

-LDFLAGS:

-Configure: '--prefix=/xclam/gcc/release/' '--disable-clamav' '--enable-debug' 'CFLAGS=-g -O0'

-sizeof(void*) = 4

-Engine flevel: 77, dconf: 77

-

-```

-

-For more detailed help, type ’man clamconf’ or ’clamconf –help’.

-

-## Output format

-

-### clamscan

-

-`clamscan` writes all regular program messages to **stdout** and errors/warnings to **stderr**. You can use the option `--stdout` to redirect all program messages to **stdout**. Warnings and error messages from `libclamav` are always printed to **stderr**. A typical output from `clamscan` looks like this:

-

-```bash

-    /tmp/test/removal-tool.exe: Worm.Sober FOUND

-    /tmp/test/md5.o: OK

-    /tmp/test/blob.c: OK

-    /tmp/test/message.c: OK

-    /tmp/test/error.hta: VBS.Inor.D FOUND

-```

-

-When a virus is found its name is printed between the `filename:` and `FOUND` strings. In case of archives the scanner depends on libclamav and only prints the first virus found within an archive:

-

-```bash

-    $ clamscan malware.zip

-    malware.zip: Worm.Mydoom.U FOUND

-```

-

-When using the –allmatch(-z) flag, clamscan may print multiple virus `FOUND` lines for archives and files.

-

-### clamd

-

-The output format of `clamd` is very similar to `clamscan`.

-

-```bash

-    $ telnet localhost 3310

-    Trying 127.0.0.1...

-    Connected to localhost.

-    Escape character is '^]'.

-    SCAN /home/zolw/test

-    /home/zolw/test/clam.exe: ClamAV-Test-File FOUND

-    Connection closed by foreign host.

-```

-

-In the **SCAN** mode it closes the connection when the first virus is found.

-

-```bash

-    SCAN /home/zolw/test/clam.zip

-    /home/zolw/test/clam.zip: ClamAV-Test-File FOUND

-```

-

-**CONTSCAN** and **MULTISCAN** don’t stop scanning in case a virus is found. Error messages are printed in the following format:

-

-```bash

-    SCAN /no/such/file

-    /no/such/file: Can't stat() the file. ERROR

-```

+Additionally, a tool called [`clamconf`](Usage/Configuration.md#clamconf) allows users to check the configurations used by each other tool, pulling information from the configuration files listed above, alongside other relevant information.

new file mode 100644

@@ -0,0 +1,126 @@

+# Configuration

+

+<!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->

+

+- [clamconf](#clamconf)

+- [clamd.conf](#clamdconf)

+	- [On-Access Scanning](#on-access-scanning)

+- [freshclam.conf](#freshclamconf)

+- [clamav-milter](#clamav-milter)

+

+<!-- /TOC -->

+

+## clamconf

+

+`clamconf` is a tool ClamAV provides for checking your entire system configuration, as it relates to your ClamAV installation. When run, it displays values used when configuring ClamAV at compilation time, important OS details, the contents (and validity) of both `clamd.conf` and `freshclam.conf`, along with other important engine, database, platform, and build information.

+

+It can also generate example configuration files for `clamd.conf` and `freshclam.conf`.

+

+To use `clamconf`, and see all the information it provides, simply run the following command:

+

+> $ clamconf

+

+For more detailed information on `clamconf`, run:

+

+> $ man clamdconf

+

+or

+

+> $ clamconf --help

+

+## clamd.conf

+

+Currently, ClamAV requires users edit their `clamd.conf.example` file before they can run the daemon. At a bare minimum, users will nee to comment out the line that reads "Example", else `clamd` will consider the configuration invalid, ala:

+

+<pre>

+  7 # Comment or remove the line below.

+  8 #Example

+  9

+</pre>

+

+You will also need to rename `clamd.conf.example` to `clamd.conf` via:

+

+> $ mv ./clamd.conf.example ./clamd.conf

+

+If you are setting up a simple, local `clamd` instance then some other configuration options of interests to you will be as follows:

+

+<pre>

+91 # Path to a local socket file the daemon will listen on.

+92 # Default: disabled (must be specified by a user)

+93 LocalSocket /tmp/clamd.socket

+

+...

+

+99 # Sets the permissions on the unix socket to the specified mode.

+100 # Default: disabled (socket is world accessible)

+101 LocalSocketMode 660

+</pre>

+

+Beyond that, `clamd.conf` is well commented and configuration should be straightforward.

+

+If needed, you can find out even more about the formatting and options available in `clamd.conf` with the command:

+

+> man clamd.conf

+

+### On-Access Scanning

+

+You can configure On-Access Scanning through `clamd.conf` (starting at *line 613* in `clamd.conf.example`) and read the [on-access](Usage.md#On-access-Scanning) section for On-Access Scanning usage details.

+

+## freshclam.conf

+

+`freshclam` is the automatic database update tool for Clam AntiVirus. It can be configured to work in two modes:

+

+- interactive - on demand from command line

+- daemon - silently in the background

+

+`freshclam` is an advanced tool: it supports scripted updates (instead of transferring the whole CVD file at each update it only transfers the differences between the latest and the current database via a special script), database version checks through DNS, proxy servers (with authentication), digital signatures and various error scenarios.

+

+**Quick test: run freshclam (as superuser) with no parameters and check the output.**

+

+> $ freshclam

+

+If everything is OK you may create the log file in /var/log (ensure the directory is owned either by *clamav* or whichever user `freshclam` will be running as):

+

+<pre>bash

+    # touch /var/log/freshclam.log

+    # chmod 600 /var/log/freshclam.log

+    # chown clamav /var/log/freshclam.log

+</pre>

+

+Now you *should* edit the configuration file `freshclam.conf` and point the *UpdateLogFile* directive to the log file. Finally, to run `freshclam` in the daemon mode, execute:

+

+<pre>bash

+    # freshclam -d

+</pre>

+

+The other way is to use the *cron* daemon. You have to add the following line to the *crontab* of **root** or **clamav** user:

+

+<pre>cron

+N * * * *   /usr/local/bin/freshclam --quiet

+</pre>

+

+to check for a new database every hour. **N should be a number between 3 and 57 of your choice. Please don’t choose any multiple of 10, because there are already too many clients using those time slots.** Proxy settings are only configurable via the configuration file and `freshclam` will require strict permission settings for the config file when `HTTPProxyPassword` is turned on.

+

+<pre>bash

+    HTTPProxyServer myproxyserver.com

+    HTTPProxyPort 1234

+    HTTPProxyUsername myusername

+    HTTPProxyPassword mypass

+</pre>

+

+## clamav-milter

+

+ClamAV includes a mail filtering tool called `clamav-milter`. This tool interfaces directly with `clamd`, and thus requires and a working `clamd` instance to run. However, `clamav-milter`'s configuration and log files are separate from that of `clamd`.

+

+Ensuring ClamAV compiles with `clamav-milter` must be done at configure time with the command:

+

+> $ ./configure [options] --enable-milter

+

+This requires having the milter library installed on your system. If *libmilter* is not installed, `./configure` will exit with this error message:

+

+<pre>bash

+        checking for mi_stop in -lmilter... no

+        configure: error: Cannot find libmilter

+</pre>

+

+While not necessarily *complicated*, setting up the `clamav-milter` is an involved process. Thus, we recommend consulting your MTA’s manual on how to best connect ClamAV with the `clamav-milter`.

new file mode 100644

@@ -0,0 +1,125 @@

+# Scanning

+<!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->

+

+- [Daemon](#daemon)

+	- [clamd](#clamd)

+	- [clamdscan](#clamdscan)

+	- [clamdtop](#clamdtop)

+	- [On-Access Scanning](#on-access-scanning)

+- [One-Time Scanning](#one-time-scanning)

+	- [clamscan](#clamscan)

+

+<!-- /TOC -->

+

+## Daemon

+

+### clamd

+

+`clamd` is a multi-threaded daemon that uses *libclamav* to scan files for viruses. Scanning behaviour can be fully configured to fit most needs by modifying `clamd.conf`.

+

+As `clamd` requires a virus signature database to run, we recommend setting up ClamAV's official signatures before running `clamd` using `freshclam`.

+

+The daemon works by listening for commands on the sockets specified in `clamd.conf`. Listening is supported over both unix local sockets and TCP sockets.

+

+**IMPORTANT:** `clamd` does not currently protect or authenticate traffic coming over the TCP socket, meaning it will accept any and all of the following commands listed from *any* source. Thus, we strongly recommend following best networking practices when setting up your `clamd` instance. I.e. don't expose your TCP socket to the Internet.

+

+Here is a quick list of the commands accepted by `clamd` over the socket.

+

+- `PING`

+- `VERSION`

+- `RELOAD`

+- `SHUTDOWN`

+- `SCAN` *file/directory*

+- `RAWSCAN` *file/directory*

+- `CONTSCAN` *file/directory*

+- `MULTISCAN` *file/directory*

+- `ALLMATCHSCAN` *file/directory*

+- `INSTREAM`

+- `FILDES`

+- `STATS`

+- `IDSESSION, END`

+

+As with most ClamAV tools, you can find out more about these by invoking the command:

+

+> $ man clamd

+

+The daemon also handles the following signals as so:

+

+- `SIGTERM` - perform a clean exit

+- `SIGHUP` - reopen the log file

+- `SIGUSR2` - reload the database

+

+It should be noted that `clamd` should not be started using the shell operator `&` or other external tools which would start it as a background process. Instead, you should run `clamd` which will load the database and then daemonize itself (unless you have specified otherwise in `clamd.conf`). After that, clamd is ready to accept connections and perform file scanning.

+

+Once you have set up your configuration to your liking, and understand how you will be sending commands to the daemon, running `clamd` itself is simple. Simply execute the command:

+

+> $ clamd

+

+### clamdscan

+

+`clamdscan` is a `clamd` client, which greatly simplifies the task of scanning files with `clamd`. It sends commands to the `clamd` daemon across the socket specified in `clamd.conf` and generates a scan report after all requested scanning has been completed by the daemon.

+

+Thus, **to run `clamdscan`, you must have an instance of `clamd` already running** as well.

+

+Please keep in mind, that as a simple scanning client, `clamdscan` cannot change scanning and engine configurations. These are tied to the `clamd` instance and the configuration you set up in `clamd.conf`. Therefore, while `clamdscan` will accept many of the same commands as its sister tool `clamscan`, it will simply ignore most of them as (by design) no mechanism exists to make ClamAV engine configuration changes over the `clamd` socket.

+

+Again, running `clamdscan`, once you have a working `clamd` instance, is simple:

+

+> $ clamdscan [*options*] [*file/directory/-*]

+

+### clamdtop

+

+`clamdtop` is a tool to monitor one or multiple instances of `clamd`. It has a colorized *ncurses* interface, which shows each job queued, memory usage, and information about the loaded signature database for the connected `clamd` instance(s). By default it will attempt to connect to the local `clamd` as defined in `clamd.conf`. However, you can specify other `clamd` instances at the command line.

+

+To learn more, use the commands

+

+> $ man clamdtop

+

+or

+

+> $ clamdtop --help

+

+### On-Access Scanning

+

+To be updated.

+

+## One-Time Scanning

+

+### clamscan

+

+`clamscan` is a command line tool which uses *libclamav* to scan files and/or directories for viruses. Unlike `clamdscan`, `clamscan` does *not* require a running `clamd` instance to function. Instead, `clamscan` will create a new engine and load in the virus database each time it is run. It will then scan the files and/or directories specified at the command line, create a scan report, and exit.

+

+By default, when loading databases, `clamscan` will check the location to which `freshclam` installed the virus database signatures. This behaviour, along with a myriad of other scanning and engine controls, can be modified by providing flags and other options at the command line.

+

+There are too many options to list all of them here. So we'll only cover a few common and more interesting ones:

+

+- `--log=FILE` - save scan report to FILE

+- `--database=FILE/DIR` - load virus database from FILE or load all supported db files from DIR

+- `--official-db-only[=yes/no(*)]` - only load official signatures

+- `-max-filesize=#n` - files larger than this will be skipped and assumed clean

+- `--max-scansize=#n` - the maximum amount of data to scan for each container file

+- `--leave-temps[=yes/no(*)]`- do not remove temporary files

+- `--file-list=FILE` - scan files from FILE

+- `--quiet` - only output error messages

+- `--bell` - sound bell on virus detection

+- `--cross-fs[=yes(*)/no]` - scan files and directories on other filesystems

+- `--move=DIRECTORY` - move infected files into DIRECTORY

+- `--copy=DIRECTORY` - copy infected files into DIRECTORY

+- `--bytecode-timeout=N` - set bytecode timeout (in milliseconds)

+- `--heuristic-alerts[=yes(*)/no]` - toggles heuristic alerts

+- `--alert-encrypted[=yes/no(*)]` - alert on encrypted archives and documents

+- `--nocerts` - disable authenticode certificate chain verification in PE files

+- `--disable-cache` - disable caching and cache checks for hash sums of scanned files

+

+To learn more about the options available when using `clamscan` please reference:

+

+> $ man clamscan

+

+and

+

+> $ clamscan --help

+

+

+Otherwise, the general usage of clamscan is:

+

+> clamscan [options] [file/directory/-]

new file mode 100644

@@ -0,0 +1,70 @@

+# Signature Testing and Management

+

+<!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->

+

+- [freshclam](#freshclam)

+- [sigtool](#sigtool)

+- [clambc](#clambc)

+

+<!-- /TOC -->

+

+## freshclam

+

+The tool `freshclam` is used to download and update ClamAV’s official virus signature databases. While easy to use in its base configuration, `freshclam` does require a working `freshclam.conf` configuration file to run (the location of which can be passed in via command line if the default search location does not fit your needs).

+

+Once you have a valid configuration file, you can invoke freshclam with the following command:

+

+> $ freshclam

+

+By default, `freshclam` will then attempt to connect to ClamAV's virus signature database distribution network. If no databases exist in the directory specified, `freshclam` will do a fresh download of the requested databases. Otherwise, `freshclam` will attempt to update existing databases, pairing them against downloaded cdiffs. If a database is found to be corrupted, it is not updated and instead replaced with a fresh download.

+

+Of course, all this behaviour--and more--can be changed to suit your needs by modifying `freshclam.conf` and/or using various command line options.

+

+You can find more information about freshclam with the commands:

+

+> $ man freshclam

+

+and

+

+> $ freshclam --help

+

+## sigtool

+

+ClamAV provides `sigtool` as a command-line testing tool for assisting users in their efforts creating and working with virus signatures. While sigtool has many uses--including crafting signatures--of particular note, is sigtool's ability to help users and analysts in determining if a file detected by *libclamav*'s virus signatures is a false positive.

+

+This can be accomplished by using the command:

+

+> $ sigtool --unpack=FILE

+

+Where FILE points to your virus signature databases. Then, once `sigtool` has finished unpacking the database into the directory from which you ran the command, you can search for the offending signature name (provided either by [`clamscan`](./Scanning.md#clamscan) scan reports or [`clamd`](./Scanning.md#clamd) logs). As an example:

+

+> $ grep "Win.Test.EICAR" ./*

+

+Or, do all that in one step with:

+

+> $ sigtool --find="Win.Test.EICAR"

+

+This should give you the offending signature(s) in question, which can then be included as part of your [false positive report](https://www.clamav.net/reports/fp).

+

+To learn more in depth information on how `sigtool` can be used to help create virus signatures and work with malicious (and non-malicious) files please reference the many online tutorials on the topic.

+

+Otherwise, information on available sigtool functions can be easily referenced with:

+

+> $ sigtool --help

+

+and

+

+> $ man sigtool

+

+

+## clambc

+

+`clambc` is Clam Anti-Virus’ bytecode signature testing tool. It can be used to test newly crafted bytecode signatures or to help verify existing bytecode is executing against a sample as expected.

+

+For more detailed help, please use:

+

+> $ man clambc

+

+or

+

+> $ clambc --help