Browse code

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

Mickey Sola authored on 2018/11/15 07:27:57
Showing 4 changed files
... ...
@@ -1,33 +1,66 @@
1 1
 # Usage
2 2
 
3
+---
4
+
5
+<!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->
6
+
7
+- [Purpose](#purpose)
8
+- [Daemon](#daemon)
9
+- [Scanner](#scanner)
10
+- [Signature Testing and Management](#signature-testing-and-management)
11
+- [Configuration](#configuration)
12
+
13
+<!-- /TOC -->
14
+
15
+---
16
+
17
+## Purpose
18
+
19
+---
20
+
3 21
 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.
4 22
 
23
+---
24
+
5 25
 ## Daemon
6 26
 
27
+---
28
+
7 29
 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:
8 30
 
9 31
   - [`clamdscan`](Usage/Scanning.md#clamdscan) - a simple scanning client
10 32
   - [`on-access scanning`](Usage/Scanning.md#On-access-scanning) - a special `clamd` thread for real-time protection
11 33
   - [`clamdtop`](Usage/Scanning.md#clamdtop) - a resource monitoring interface for `clamd`
12 34
 
35
+---
36
+
13 37
 ## Scanner
14 38
 
39
+---
40
+
15 41
 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.
16 42
 
43
+---
44
+
17 45
 ## Signature Testing and Management
18 46
 
47
+---
48
+
19 49
 A number of tools allow for [testing and management of signatures](Usage/SignatureManagement.md). Of note are the following:
20 50
 
21 51
   - [`clambc`](Usage/SignatureManagement.md#clambc) - specifically for testing bytecode
22 52
   - [`sigtool`](Usage/SignatureManagement.md#sigtool) - for general signature testing and analysis
23 53
   - [`freshclam`](Usage/SignatureManagement.md#freshclam) - used to update signature database sets to the latest version
24 54
 
55
+---
25 56
 
26 57
 ## Configuration
27 58
 
28
-The more complex tools ClamAV provides each require some degree of [configuration](Usage/Configuration.md). ClamAV supplies two examples configuration files:
59
+---
60
+
61
+The more complex tools ClamAV provides each require some degree of [configuration](Usage/Configuration.md). ClamAV supplies two example configuration files:
29 62
 
30
-  - [`clamd.conf`](Usage/Configuration.md#clamd-configuration) - for configuring the behaviour of the ClamAV Daemon `clamd` and associated tools
31
-  - [`freschclam.conf`](Usage/Configuration.md#freshclam-configuration) - for configuring the behaviour of the signature database update tool, `freshclam`
63
+  - [`clamd.conf`](Usage/Configuration.md#clamdconf) - for configuring the behaviour of the ClamAV Daemon `clamd` and associated tools
64
+  - [`freschclam.conf`](Usage/Configuration.md#freshclamconf) - for configuring the behaviour of the signature database update tool, `freshclam`
32 65
 
33 66
 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.
... ...
@@ -1,5 +1,7 @@
1 1
 # Configuration
2 2
 
3
+---
4
+
3 5
 <!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->
4 6
 
5 7
 - [clamconf](#clamconf)
... ...
@@ -10,11 +12,15 @@
10 10
 
11 11
 <!-- /TOC -->
12 12
 
13
+---
14
+
13 15
 ## clamconf
14 16
 
17
+---
18
+
15 19
 `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.
16 20
 
17
-It can also generate example configuration files for `clamd.conf` and `freshclam.conf`.
21
+It can also generate example configuration files for [`clamd.conf`](#clamdconf) and [`freshclam.conf`](#freshclamconf).
18 22
 
19 23
 To use `clamconf`, and see all the information it provides, simply run the following command:
20 24
 
... ...
@@ -28,9 +34,13 @@ or
28 28
 
29 29
 > $ clamconf --help
30 30
 
31
+---
32
+
31 33
 ## clamd.conf
32 34
 
33
-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:
35
+---
36
+
37
+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:
34 38
 
35 39
 <pre>
36 40
   7 # Comment or remove the line below.
... ...
@@ -42,7 +52,7 @@ You will also need to rename `clamd.conf.example` to `clamd.conf` via:
42 42
 
43 43
 > $ mv ./clamd.conf.example ./clamd.conf
44 44
 
45
-If you are setting up a simple, local `clamd` instance then some other configuration options of interests to you will be as follows:
45
+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:
46 46
 
47 47
 <pre>
48 48
 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
62 62
 
63 63
 > man clamd.conf
64 64
 
65
+---
66
+
65 67
 ### On-Access Scanning
66 68
 
69
+---
70
+
67 71
 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.
68 72
 
73
+---
74
+
69 75
 ## freshclam.conf
70 76
 
77
+---
78
+
71 79
 `freshclam` is the automatic database update tool for Clam AntiVirus. It can be configured to work in two modes:
72 80
 
73 81
 - 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
108 108
     HTTPProxyPassword mypass
109 109
 </pre>
110 110
 
111
+---
112
+
111 113
 ## clamav-milter
112 114
 
113
-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`.
115
+---
116
+
117
+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`.
114 118
 
115 119
 Ensuring ClamAV compiles with `clamav-milter` must be done at configure time with the command:
116 120
 
... ...
@@ -1,4 +1,7 @@
1 1
 # Scanning
2
+
3
+---
4
+
2 5
 <!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->
3 6
 
4 7
 - [Daemon](#daemon)
... ...
@@ -11,17 +14,21 @@
11 11
 
12 12
 <!-- /TOC -->
13 13
 
14
+---
15
+
14 16
 ## Daemon
15 17
 
18
+---
19
+
16 20
 ### clamd
17 21
 
18
-`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`.
22
+`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).
19 23
 
20
-As `clamd` requires a virus signature database to run, we recommend setting up ClamAV's official signatures before running `clamd` using `freshclam`.
24
+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).
21 25
 
22 26
 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.
23 27
 
24
-**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.
28
+**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.**
25 29
 
26 30
 Here is a quick list of the commands accepted by `clamd` over the socket.
27 31
 
... ...
@@ -49,27 +56,31 @@ The daemon also handles the following signals as so:
49 49
 - `SIGHUP` - reopen the log file
50 50
 - `SIGUSR2` - reload the database
51 51
 
52
-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.
52
+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.
53 53
 
54 54
 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:
55 55
 
56 56
 > $ clamd
57 57
 
58
+---
59
+
58 60
 ### clamdscan
59 61
 
60
-`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.
62
+`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.
61 63
 
62 64
 Thus, **to run `clamdscan`, you must have an instance of `clamd` already running** as well.
63 65
 
64
-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.
66
+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.
65 67
 
66
-Again, running `clamdscan`, once you have a working `clamd` instance, is simple:
68
+Again, running `clamdscan`, once you have a [working `clamd` instance](#clamd), is simple:
67 69
 
68 70
 > $ clamdscan [*options*] [*file/directory/-*]
69 71
 
72
+---
73
+
70 74
 ### clamdtop
71 75
 
72
-`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.
76
+`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.
73 77
 
74 78
 To learn more, use the commands
75 79
 
... ...
@@ -79,17 +90,25 @@ or
79 79
 
80 80
 > $ clamdtop --help
81 81
 
82
+---
83
+
82 84
 ### On-Access Scanning
83 85
 
86
+---
87
+
84 88
 To be updated.
85 89
 
90
+---
91
+
86 92
 ## One-Time Scanning
87 93
 
94
+---
95
+
88 96
 ### clamscan
89 97
 
90 98
 `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.
91 99
 
92
-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.
100
+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.
93 101
 
94 102
 There are too many options to list all of them here. So we'll only cover a few common and more interesting ones:
95 103
 
... ...
@@ -1,5 +1,7 @@
1 1
 # Signature Testing and Management
2 2
 
3
+---
4
+
3 5
 <!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->
4 6
 
5 7
 - [freshclam](#freshclam)
... ...
@@ -8,9 +10,13 @@
8 8
 
9 9
 <!-- /TOC -->
10 10
 
11
+---
12
+
11 13
 ## freshclam
12 14
 
13
-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).
15
+---
16
+
17
+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).
14 18
 
15 19
 Once you have a valid configuration file, you can invoke freshclam with the following command:
16 20
 
... ...
@@ -18,7 +24,7 @@ Once you have a valid configuration file, you can invoke freshclam with the foll
18 18
 
19 19
 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.
20 20
 
21
-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.
21
+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).
22 22
 
23 23
 You can find more information about freshclam with the commands:
24 24
 
... ...
@@ -28,8 +34,12 @@ and
28 28
 
29 29
 > $ freshclam --help
30 30
 
31
+---
32
+
31 33
 ## sigtool
32 34
 
35
+---
36
+
33 37
 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.
34 38
 
35 39
 This can be accomplished by using the command:
... ...
@@ -56,9 +66,12 @@ and
56 56
 
57 57
 > $ man sigtool
58 58
 
59
+---
59 60
 
60 61
 ## clambc
61 62
 
63
+---
64
+
62 65
 `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.
63 66
 
64 67
 For more detailed help, please use: