What this module does #
An antivirus compares the files on your server against a catalog of signatures of known malware. If something matches, it flags it as infected so it can't keep circulating — for example, a malicious attachment uploaded to a public folder or a tainted file that arrived over FTP.
The clamav module puts the ClamAV engine within reach through a handful of clear commands: check its status, scan whatever path you want (a file or an entire tree), decide what to do with anything infected — just report it, delete it or move it to a safe quarantine from which you can restore it later — and keep the signature database current with freshclam. Quarantine isolates the file without deleting it, so you never lose anything by mistake.
A scan detects with whatever signature database you have at that moment. If you haven't updated in days, run imaxe clamav update first so you don't miss recent threats. Scanning large trees can take time and use CPU: narrow the path down to what you really want to check.
Common tasks #
Pick what you want to do. Each recipe comes with the command ready to go — just swap the path for yours and hit Copy.
1
See whether ClamAV is ready
Checks the engine, the mode and how old your signatures are.
Connect to your server over SSH and ask for the overall status:
$ sudo imaxe clamav statusInterested only in the signature database — version, date and files? Use db:
$ sudo imaxe clamav db2
Scan a folder
Check a path and keep the report, without touching anything.
Scan a directory and all its contents with --recursive. By default it only reports: it deletes and moves nothing.
$ sudo imaxe clamav scan /home --recursiveJust a single file? Pass it the direct path, without --recursive:
$ sudo imaxe clamav scan /srv/uploads/factura.pdf3
Scan and isolate what's infected
Automatically moves everything that tests positive to quarantine.
Scan a path and, with --quarantine, move each infected file into quarantine instead of leaving it where it is:
$ sudo imaxe clamav scan /srv/uploads --recursive --quarantineIf you'd rather delete what's infected outright instead of isolating it, use --remove (it's irreversible, use it wisely):
$ sudo imaxe clamav scan /srv/uploads --recursive --remove4
Review and restore the quarantine
See what's isolated and recover a false positive if you need to.
List what's in quarantine — each entry comes with its identifier, source, signature and date:
$ sudo imaxe clamav quarantine listWas it a false positive? Restore it to its original path using the identifier shown in the list:
$ sudo imaxe clamav quarantine restore a1b2c3d4Once you confirm that everything isolated is junk, empty the quarantine for good:
$ sudo imaxe clamav quarantine purge --yes5
Update the signatures
Download the latest definitions to detect new threats.
Run freshclam to fetch the most recent signature database:
$ sudo imaxe clamav updateAfterwards, confirm the database is up to date with its version and date:
$ sudo imaxe clamav db--removeDeleting removes the file with no way back, and no antivirus is free of false positives. When in doubt, always use --quarantine: it isolates just as well and lets you restore if you got it wrong.
Synopsis #
imaxe clamav <subcomando> [<ruta>] [--recursive] [--quarantine|--remove] [--json]The subcommands that scan, move or delete files require root privileges (use sudo), because they read other users' paths and write to the system quarantine. Add --json to any command for machine-readable output, suitable for scripting.
Subcommands #
| Subcommand | What it does | Relevant flags |
|---|---|---|
| status | ClamAV status: engine, mode (daemon/on-demand), freshclam and signature database. | --json |
| scan | Scans a path; can report, delete or quarantine what's infected. | --recursive, --remove, --quarantine, --json |
| update | Updates the signature database via freshclam. | --json |
| db | Signature database information: version, date and files. | --json |
| quarantine | Manages the quarantine of infected files (subcommand group). | list · restore · purge |
The quarantine group gathers three subcommands:
| Subcommand | What it does | Relevant flags |
|---|---|---|
| quarantine list | Lists the files in quarantine (source, signature, date). | --json |
| quarantine restore | Restores a file from quarantine to its original path or a given destination. | <id> [<destino>] |
| quarantine purge | Permanently deletes everything in quarantine. | --yes |
Arguments and flags #
| Flag / argument | Type | Default | Description |
|---|---|---|---|
| <ruta> req. | path | — | In scan, file or directory to scan. |
| <id> req. | string | — | In quarantine restore, identifier of the quarantined item (shown in quarantine list). |
| <destino> | path | ruta original | In quarantine restore, path to restore the file to. Defaults to its original location. |
| --recursive | bool | false | In scan, recursive scan of directories. |
| --quarantine | bool | false | In scan, moves the infected files to quarantine. |
| --remove | bool | false | In scan, deletes the infected files. Irreversible; mutually exclusive with --quarantine. |
| --yes | bool | false | In quarantine purge, confirms the deletion without asking. |
| --json | bool | false | Emits the result as JSON on stdout. Available in every subcommand. |
Files and paths #
| Path | Contents |
|---|---|
| /etc/imaxe/clamav.yml | Module configuration: quarantine directory and paths excluded from the scan. |
| /var/lib/imaxe/clamav/quarantine | Quarantine store: this is where infected files that can be restored are isolated. |
| /var/lib/clamav/ | Signature database maintained by freshclam (malware definitions). |
| /var/log/imaxe/clamav.log | Structured log of every scan, quarantine and update. |
Example clamav.yml:
quarantine_dir: /var/lib/imaxe/clamav/quarantine
scan:
exclude:
- /proc
- /sysscan.exclude is a list of paths the scan skips; it comes empty by default.
Exit codes and logs #
Each run returns a code you can check with echo $? — handy for chaining in scripts:
Follow the log live while you troubleshoot:
$ sudo tail -f /var/log/imaxe/clamav.logTroubleshooting #
| Symptom | Likely cause | Fix |
|---|---|---|
| You get INFECTED (code 3) | The scan detected one or more threats. | Review the report; run scan again with --quarantine to isolate them. |
| You get UPDATE (code 4) | freshclam couldn't download the signatures (network or mirror down). | Check the server's Internet access and retry clamav update. |
| The scan takes too long | The path covers too many files or system paths. | Narrow the path down and exclude what's unnecessary with scan.exclude in clamav.yml. |
| I lost a legitimate file | False positive moved to quarantine by --quarantine. | Locate it with quarantine list and recover it with quarantine restore <id>. |
| The status shows stale signatures | freshclam hasn't run in a while. | Run clamav update and verify with clamav db. |
Stuck with the ClamAV module?
Write to us with the output of «imaxe <module> status --json» and we'll get back to you fast.