open-dsi
/
clamav
mirror of https://github.com/Cisco-Talos/clamav
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs - adding links to Usage documentations along with some other formatting touchups

Browse Source
pull/51/head
Mickey Sola 7 years ago committed by Micah Snyder
parent 6ed3d579a7
commit ab012ecae8
4 changed files with 105 additions and 18 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 39
      docs/UserManual/Usage.md
  2. 30
      docs/UserManual/Usage/Configuration.md
  3. 37
      docs/UserManual/Usage/Scanning.md
  4. 17
      docs/UserManual/Usage/SignatureManagement.md

39
docs/UserManual/Usage.md
Unescape View File

@ -1,33 +1,66 @@
# Usage
---
<!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->
- [Purpose](#purpose)
- [Daemon](#daemon)
- [Scanner](#scanner)
- [Signature Testing and Management](#signature-testing-and-management)
- [Configuration](#configuration)
<!-- /TOC -->
---
## Purpose
---
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.
---
## Daemon
---
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:
- [`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`
---
## Scanner
---
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.
---
## Signature Testing and Management
---
A number of tools allow for [testing and management of signatures](Usage/SignatureManagement.md). Of note are the following:
- [`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
---
## Configuration
The more complex tools ClamAV provides each require some degree of [configuration](Usage/Configuration.md). ClamAV supplies two examples configuration files:
---
The more complex tools ClamAV provides each require some degree of [configuration](Usage/Configuration.md). ClamAV supplies two example configuration files:
- [`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`
- [`clamd.conf`](Usage/Configuration.md#clamdconf) - for configuring the behaviour of the ClamAV Daemon `clamd` and associated tools
- [`freschclam.conf`](Usage/Configuration.md#freshclamconf) - for configuring the behaviour of the signature database update tool, `freshclam`
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.

30
docs/UserManual/Usage/Configuration.md
Unescape View File

@ -1,5 +1,7 @@
# Configuration
---
<!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->
- [clamconf](#clamconf)
@ -10,11 +12,15 @@
<!-- /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`.
It can also generate example configuration files for [`clamd.conf`](#clamdconf) and [`freshclam.conf`](#freshclamconf).
To use `clamconf`, and see all the information it provides, simply run the following command:
@ -28,9 +34,13 @@ 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:
---
Currently, ClamAV requires users to 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.
@ -42,7 +52,7 @@ 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:
If you are setting up a simple, local [`clamd` instance](Scanning.md#clamd) 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.
@ -62,12 +72,20 @@ If needed, you can find out even more about the formatting and options available
> 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
@ -108,9 +126,13 @@ to check for a new database every hour. **N should be a number between 3 and 57
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`.
---
ClamAV includes a mail filtering tool called `clamav-milter`. This tool interfaces directly with `clamd`, and thus requires and a working [`clamd` instance](Scanning.md#clamd) 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:

37
docs/UserManual/Usage/Scanning.md
Unescape View File

@ -1,4 +1,7 @@
# Scanning
---
<!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->
- [Daemon](#daemon)
@ -11,17 +14,21 @@
<!-- /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`.
`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`](Configuration.md#clamdconf).
As `clamd` requires a virus signature database to run, we recommend setting up ClamAV's official signatures before running `clamd` using `freshclam`.
As `clamd` requires a virus signature database to run, we recommend setting up ClamAV's official signatures before running `clamd` [using `freshclam`](SignatureManagement.md#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.
**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 open Internet.**
Here is a quick list of the commands accepted by `clamd` over the socket.
@ -49,27 +56,31 @@ The daemon also handles the following signals as so:
- `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.
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`](Configuration.md#clamdconf)). 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.
`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`](Configuration.md#clamdconf) 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.
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`](Configuration.md#clamdconf). 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:
Again, running `clamdscan`, once you have a [working `clamd` instance](#clamd), 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.
`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`](Configuration.md#clamdconf). However, you can specify other `clamd` instances at the command line.
To learn more, use the commands
@ -79,17 +90,25 @@ 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.
By default, when loading databases, `clamscan` will check the location to which [`freshclam` installed the virus database signatures](SignatureManagement.md#freshclam). 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:

17
docs/UserManual/Usage/SignatureManagement.md
Unescape View File

@ -1,5 +1,7 @@
# Signature Testing and Management
---
<!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->
- [freshclam](#freshclam)
@ -8,9 +10,13 @@
<!-- /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).
---
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](Configuration.md#freshclam) 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:
@ -18,7 +24,7 @@ Once you have a valid configuration file, you can invoke freshclam with the foll
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.
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](Configuration.md#freshclamconf).
You can find more information about freshclam with the commands:
@ -28,8 +34,12 @@ 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:
@ -56,9 +66,12 @@ 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:

Write Preview
Loading…
Cancel
Save