Browse code

docs - updating Usage docs based on feedback

Mickey Sola authored on 2018/11/17 00:52:34
Showing 4 changed files
... ...
@@ -29,7 +29,7 @@ This User Guide presents an overview of the various ways that *libclamav* can be
29 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:
30 30
 
31 31
   - [`clamdscan`](Usage/Scanning.md#clamdscan) - a simple scanning client
32
-  - [`on-access scanning`](Usage/Scanning.md#On-access-scanning) - a special `clamd` thread for real-time protection
32
+  - [`on-access scanning`](Usage/Scanning.md#On-access-scanning) - provides real-time protection via a `clamd` instance
33 33
   - [`clamdtop`](Usage/Scanning.md#clamdtop) - a resource monitoring interface for `clamd`
34 34
 
35 35
 ---
... ...
@@ -63,4 +63,6 @@ The more complex tools ClamAV provides each require some degree of [configuratio
63 63
   - [`clamd.conf`](Usage/Configuration.md#clamdconf) - for configuring the behaviour of the ClamAV Daemon `clamd` and associated tools
64 64
   - [`freschclam.conf`](Usage/Configuration.md#freshclamconf) - for configuring the behaviour of the signature database update tool, `freshclam`
65 65
 
66
+ClamAV also provides a mail filtering tool called [`clamav-milter`](Usage/Configuration.md#clamav-milter) which can be attached to a `clamd` instance for mail scanning purposes.
67
+
66 68
 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.
... ...
@@ -24,15 +24,15 @@ It can also generate example configuration files for [`clamd.conf`](#clamdconf)
24 24
 
25 25
 To use `clamconf`, and see all the information it provides, simply run the following command:
26 26
 
27
-> $ clamconf
27
+> `$ clamconf`
28 28
 
29 29
 For more detailed information on `clamconf`, run:
30 30
 
31
-> $ man clamdconf
31
+> `$ man clamconf`
32 32
 
33 33
 or
34 34
 
35
-> $ clamconf --help
35
+> `$ clamconf --help`
36 36
 
37 37
 ---
38 38
 
... ...
@@ -40,37 +40,36 @@ or
40 40
 
41 41
 ---
42 42
 
43
-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:
43
+Currently, ClamAV requires users to edit their `clamd.conf.example` file before they can run the daemon. At a bare minimum, users will need to comment out the line that reads "Example", else `clamd` will consider the configuration invalid, ala:
44 44
 
45 45
 <pre>
46 46
   7 # Comment or remove the line below.
47 47
   8 #Example
48
-  9
49 48
 </pre>
50 49
 
51 50
 You will also need to rename `clamd.conf.example` to `clamd.conf` via:
52 51
 
53
-> $ mv ./clamd.conf.example ./clamd.conf
52
+> `$ mv ./clamd.conf.example ./clamd.conf`
54 53
 
55 54
 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:
56 55
 
57 56
 <pre>
58
-91 # Path to a local socket file the daemon will listen on.
59
-92 # Default: disabled (must be specified by a user)
60
-93 LocalSocket /tmp/clamd.socket
57
+	91 # Path to a local socket file the daemon will listen on.
58
+	92 # Default: disabled (must be specified by a user)
59
+	93 LocalSocket /tmp/clamd.socket
61 60
 
62
-...
61
+	...
63 62
 
64
-99 # Sets the permissions on the unix socket to the specified mode.
65
-100 # Default: disabled (socket is world accessible)
66
-101 LocalSocketMode 660
63
+	99 # Sets the permissions on the unix socket to the specified mode.
64
+	100 # Default: disabled (socket is world accessible)
65
+	101 LocalSocketMode 660
67 66
 </pre>
68 67
 
69 68
 Beyond that, `clamd.conf` is well commented and configuration should be straightforward.
70 69
 
71 70
 If needed, you can find out even more about the formatting and options available in `clamd.conf` with the command:
72 71
 
73
-> man clamd.conf
72
+> `man clamd.conf`
74 73
 
75 74
 ---
76 75
 
... ...
@@ -78,7 +77,9 @@ If needed, you can find out even more about the formatting and options available
78 78
 
79 79
 ---
80 80
 
81
-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.
81
+You can configure On-Access Scanning through `clamd.conf`.  Configuration for On-Access Scanning starts at *line 613* in `clamd.conf.example`.
82
+
83
+Please read the [on-access](Usage.md#On-access-Scanning) section of the Usage manual for further details on using On-Access Scanning.
82 84
 
83 85
 ---
84 86
 
... ...
@@ -95,35 +96,35 @@ You can configure On-Access Scanning through `clamd.conf` (starting at *line 613
95 95
 
96 96
 **Quick test: run freshclam (as superuser) with no parameters and check the output.**
97 97
 
98
-> $ freshclam
98
+> `$ freshclam`
99 99
 
100 100
 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):
101 101
 
102
-<pre>bash
103
-    # touch /var/log/freshclam.log
104
-    # chmod 600 /var/log/freshclam.log
105
-    # chown clamav /var/log/freshclam.log
102
+<pre>
103
+	# touch /var/log/freshclam.log
104
+	# chmod 600 /var/log/freshclam.log
105
+	# chown clamav /var/log/freshclam.log
106 106
 </pre>
107 107
 
108 108
 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:
109 109
 
110
-<pre>bash
111
-    # freshclam -d
110
+<pre>
111
+	# freshclam -d
112 112
 </pre>
113 113
 
114 114
 The other way is to use the *cron* daemon. You have to add the following line to the *crontab* of **root** or **clamav** user:
115 115
 
116
-<pre>cron
117
-N * * * *   /usr/local/bin/freshclam --quiet
116
+<pre>
117
+	N * * * *   /usr/local/bin/freshclam --quiet
118 118
 </pre>
119 119
 
120 120
 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.
121 121
 
122
-<pre>bash
123
-    HTTPProxyServer myproxyserver.com
124
-    HTTPProxyPort 1234
125
-    HTTPProxyUsername myusername
126
-    HTTPProxyPassword mypass
122
+<pre>
123
+	HTTPProxyServer myproxyserver.com
124
+	HTTPProxyPort 1234
125
+	HTTPProxyUsername myusername
126
+	HTTPProxyPassword mypass
127 127
 </pre>
128 128
 
129 129
 ---
... ...
@@ -132,17 +133,17 @@ to check for a new database every hour. **N should be a number between 3 and 57
132 132
 
133 133
 ---
134 134
 
135
-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`.
135
+ClamAV includes a mail filtering tool called `clamav-milter`. This tool interfaces directly with `clamd`, and thus requires a working [`clamd` instance](Scanning.md#clamd) to run. However, `clamav-milter`'s configuration and log files are separate from that of `clamd`.
136 136
 
137 137
 Ensuring ClamAV compiles with `clamav-milter` must be done at configure time with the command:
138 138
 
139
-> $ ./configure [options] --enable-milter
139
+> `$ ./configure [options] --enable-milter`
140 140
 
141 141
 This requires having the milter library installed on your system. If *libmilter* is not installed, `./configure` will exit with this error message:
142 142
 
143
-<pre>bash
144
-        checking for mi_stop in -lmilter... no
145
-        configure: error: Cannot find libmilter
143
+<pre>
144
+	checking for mi_stop in -lmilter... no
145
+	configure: error: Cannot find libmilter
146 146
 </pre>
147 147
 
148 148
 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`.
... ...
@@ -41,7 +41,7 @@ Here is a quick list of the commands accepted by `clamd` over the socket.
41 41
 
42 42
 As with most ClamAV tools, you can find out more about these by invoking the command:
43 43
 
44
-> $ man clamd
44
+> `$ man clamd`
45 45
 
46 46
 The daemon also handles the following signals as so:
47 47
 
... ...
@@ -53,7 +53,7 @@ It should be noted that `clamd` should not be started using the shell operator `
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
-> $ clamd
56
+> `$ clamd`
57 57
 
58 58
 ### clamdscan
59 59
 
... ...
@@ -65,7 +65,7 @@ Please keep in mind, that as a simple scanning client, `clamdscan` cannot change
65 65
 
66 66
 Again, running `clamdscan`, once you have a working `clamd` instance, is simple:
67 67
 
68
-> $ clamdscan [*options*] [*file/directory/-*]
68
+> `$ clamdscan [*options*] [*file/directory/-*]`
69 69
 
70 70
 ### clamdtop
71 71
 
... ...
@@ -73,21 +73,21 @@ Again, running `clamdscan`, once you have a working `clamd` instance, is simple:
73 73
 
74 74
 To learn more, use the commands
75 75
 
76
-> $ man clamdtop
76
+> `$ man clamdtop`
77 77
 
78 78
 or
79 79
 
80
-> $ clamdtop --help
80
+> `$ clamdtop --help`
81 81
 
82 82
 ### On-Access Scanning
83 83
 
84
-There is a special thread in `clamd` that performs On-Access Scanning under Linux. This thread shares the virus signature database with the daemon and is capable of blocking discovered threats at the kernel level, although by default it is only configured to alert on detection.
84
+The ClamAV daemon can be configured to perform On-Access Scanning under Linux. ClamAV's On-Access Scanning runs *alongside* the `clamd` instance, and shares the same engine and virus signature database with the daemon used to kick it off. The On-Access Scanner is capable of blocking access to/from any malicious files it discovers, but by default it is configured to only alert the user if it detects a malicious file.
85 85
 
86 86
 You can can set-up On-Access Scanning [through `clamd.conf`](Configuration.md#on-access-scanning) and learn more about the options available to you by reading the [On-Access Scanning User Guide](../OnAccess.md).
87 87
 
88
-Once you have set up the On-Access Scanner to your liking, you will need to run `clamd` as *root* (or another user with elevated permissions) to start it:
88
+Once you have set up the On-Access Scanner (and `clamd`) to your liking, you will need to run `clamd` as *root* (or another user with elevated permissions) to start it:
89 89
 
90
-> $ sudo clamd
90
+> `$ sudo clamd`
91 91
 
92 92
 ## One-Time Scanning
93 93
 
... ...
@@ -102,7 +102,7 @@ There are too many options to list all of them here. So we'll only cover a few c
102 102
 - `--log=FILE` - save scan report to FILE
103 103
 - `--database=FILE/DIR` - load virus database from FILE or load all supported db files from DIR
104 104
 - `--official-db-only[=yes/no(*)]` - only load official signatures
105
-- `-max-filesize=#n` - files larger than this will be skipped and assumed clean
105
+- `--max-filesize=#n` - files larger than this will be skipped and assumed clean
106 106
 - `--max-scansize=#n` - the maximum amount of data to scan for each container file
107 107
 - `--leave-temps[=yes/no(*)]`- do not remove temporary files
108 108
 - `--file-list=FILE` - scan files from FILE
... ...
@@ -119,13 +119,13 @@ There are too many options to list all of them here. So we'll only cover a few c
119 119
 
120 120
 To learn more about the options available when using `clamscan` please reference:
121 121
 
122
-> $ man clamscan
122
+> `$ man clamscan`
123 123
 
124 124
 and
125 125
 
126
-> $ clamscan --help
126
+> `$ clamscan --help`
127 127
 
128 128
 
129 129
 Otherwise, the general usage of clamscan is:
130 130
 
131
-> clamscan [options] [file/directory/-]
131
+> `clamscan [options] [file/directory/-]`
... ...
@@ -28,11 +28,11 @@ Of course, all this behaviour--and more--can be changed to suit your needs by [m
28 28
 
29 29
 You can find more information about freshclam with the commands:
30 30
 
31
-> $ man freshclam
31
+> $ `man freshclam`
32 32
 
33 33
 and
34 34
 
35
-> $ freshclam --help
35
+> $ `freshclam --help`
36 36
 
37 37
 ---
38 38
 
... ...
@@ -44,15 +44,15 @@ ClamAV provides `sigtool` as a command-line testing tool for assisting users in
44 44
 
45 45
 This can be accomplished by using the command:
46 46
 
47
-> $ sigtool --unpack=FILE
47
+> $ `sigtool --unpack=FILE`
48 48
 
49 49
 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:
50 50
 
51
-> $ grep "Win.Test.EICAR" ./*
51
+> $ `grep "Win.Test.EICAR" ./*`
52 52
 
53 53
 Or, do all that in one step with:
54 54
 
55
-> $ sigtool --find="Win.Test.EICAR"
55
+> $ `sigtool --find="Win.Test.EICAR"`
56 56
 
57 57
 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).
58 58
 
... ...
@@ -60,11 +60,11 @@ To learn more in depth information on how `sigtool` can be used to help create v
60 60
 
61 61
 Otherwise, information on available sigtool functions can be easily referenced with:
62 62
 
63
-> $ sigtool --help
63
+> $ `sigtool --help`
64 64
 
65 65
 and
66 66
 
67
-> $ man sigtool
67
+> $ `man sigtool`
68 68
 
69 69
 ---
70 70
 
... ...
@@ -76,8 +76,8 @@ and
76 76
 
77 77
 For more detailed help, please use:
78 78
 
79
-> $ man clambc
79
+> $ `man clambc`
80 80
 
81 81
 or
82 82
 
83
-> $ clambc --help
83
+> $ `clambc --help`