% !TeX root = sigui-manual.tex
\lstset{breaklines=true,basicstyle=\footnotesize\ttfamily}
\chapter{Usage examples}
\section{Configuring a proxy}
\Gls{freshclam} by default attemps to connect to the Internet directly. If you can only access the Internet by using a proxy, then you should configure the proxy using SigUI.

If you have already configured a system wide proxy setting, then easiest is to just press the \emph{Retrieve system proxy settings} button on the \emph{Updater configuration} tab.
This will retrieve the proxy settings from Internet Explorer, and display them in the \emph{Proxy settings} section. 
If the settings are correct, click \emph{Save settings}.

You can also manually input the proxy settings:
\label{sec:proxysettings}
\begin{itemize}
\item Tick the \emph{Proxy required for Internet access} checkbox
\item Set the proxy server and port in the \emph{Proxy server:} and \emph{Proxy port:} fields
\item If the proxy requires a username and password, then tick the \emph{Authentication required} checkbox
\begin{itemize}
\item Enter the username in the \emph{Proxy username:} field
\item Enter the password in the \emph{Proxy password:} field \footnote{Note that the password will be saved as cleartext in \gls{freshclam.conf}}
\end{itemize}
\item Check that the settings are correct
\item Click \emph{Save settings}
\end{itemize}

To test whether the proxy settings work, click \emph{Run freshclam to test configuration}.
This will run \gls{freshclam}, and display an error if it failed to connect through the proxy.
See \prettyref{sec:runfreshclam} for details.

\section{Choosing a mirror}
\label{sec:mirror}
\Gls{freshclam} by default uses the \gls{db.local.win.clamav.net} \gls{mirror}. Although this works well most of the time, you can get better download speeds by using a mirror from your country:
\begin{itemize}
\item Open SigUI
\item Open the \emph{Download Official Signatures from mirror} dropdown \footnote{
On the \emph{Updater configuration} tab, in the \emph{Signature sources} section}
\item Mirrors are of the form \texttt{db.XY.clamav.net}, where \emph{XY} is your two-letter country-code
\item Select the mirror corresponding to your country
\item Click \emph{Save settings}
\end{itemize}

You can also enter the \gls{hostname} of the mirror you wish to use, instead of choosing one from the dropdown. 
This mirror can be a server on your own network too. See \prettyref{sec:localmirror}.

\section{Deploying custom signature updates}
\label{sec:customsigs}
In addition to the official virus signatures, you can use your own signatures, or signatures provided by third-parties.
To deploy them you have these choices:
\begin{itemize}
 \item Put your custom signatures on your own webserver. See \prettyref{sec:customweb}
 \item Put your custom signatures on a network share. See \prettyref{sec:customnet}
 \item Manually copy your custom signatures each time you change them. See \prettyref{sec:custommanual}
 \item Write and deploy a script that copies the signatures to a local drive, and runs SigUI in command-line mode. See \prettyref{sec:customautomatedcopy}
\end{itemize}

A reload of the signatures is queued once the signatures are installed. See \prettyref{sec:updatenow}.

\subsection{Deploying your own signatures from a webserver}
\label{sec:customweb}
If you have written your own signatures and want to deploy them to multiple
\CW installations on your network, then the easiest is to put the signatures on your webserver (in your LAN).

The custom signature can be in any format that \gls{ClamAV} understands.
See \url{http://www.clamav.net/doc/latest/signatures.pdf} section 3 "Signature formats" for details about the format.
All the signature files, except CVD, are ASCII files. Both Unix (LF) and Windows-style (CR+LF) line-endings are accepted.
CVD files are binary files though, so you should not modify them.
The format of signatures is determined based on the database extension (in a case insensitive manner), so you must make sure to preserve the file's contents and
extension when copying it. (You can safely rename the file, as long as you preserve the extension).

Since these files are not digitally signed \footnote{Official \gls{CVD} files are digitally signed}, it is your responsibility to ensure that the signature files are not altered (by malware, etc.).

Deploying a new signature file is easy:
\begin{itemize}
\item Copy the signature to your webserver, at a location of your choice
\item Open SigUI
\item Click the \emph{Add} button next to the \emph{Custom signature URLs} section
\item Enter the full URL to your new signature file
\item Click OK.
\item Click \emph{Save settings}
\item See \prettyref{sec:ui_urladd} for details
\item You can repeat this operation on each machine that has \CW installed, or you can automate it, see \prettyref{sec:deploy_conf}
\end{itemize}

\subsection{Deploying your own signatures from a network share}
\label{sec:customnet}
This is similar to downloading a signature file from a webserver, see \prettyref{sec:customweb}.
Except you have to add an \gls{UNC path} instead of an \verb+http://+ URL.

However \CW requires this \gls{UNC path} to be readable by the \gls{SYSTEM account}.
Usually network shares, and network mapped drives are not accessible to this user.
If you have made them accessible (it is out of scope for this document to discuss how), then you can of course use them in SigUI.

\subsection{Deploying third-party signatures}

If you want to deploy third-party signatures that are not in \gls{CVD} format \footnote{freshclam supports third-party signatures in CVD format, but there are no such signatures yet}, you can do so with some additional steps:
\begin{itemize}
\item Download the third-party signatures to your server
\item Check their integrity by comparing against the third-party supplied checksum and digital signatures. There usually are scripts to accomplish this
\item Copy the signatures to your webserver, at a location of your choice
\item Make sure you preserve the extension of the files, as the signature format is determined based on the extension
\item Add the full URL path to these signatures to \gls{freshclam.conf} using \gls{SigUI}.
See \prettyref{sec:ui_urladd}
\end{itemize}

Note that if you add third-party signatures memory usage will increase (depending on the complexity and size of the signatures), and performance may be different.

Note that the downloaded signature files will all be placed in the same directory. Hence you must make sure you don't have two URLs that, when downloaded, have the same filename.
The UI will warn you if you try to do that\footnote{the two URLs with same filenames will just keep overwriting the same file}.

\subsection{Manually copying custom signatures to database directory}
\label{sec:custommanual}
If you want \gls{ClamAV} to use a custom signature, you just need to copy it to its database directory. However, as explained earlier in this document, that directory is protected against changes so you need to use SigUI to copy the databases.

This can be achieved by using the \emph{Local signature management} tab:
\begin{itemize}
\item Click \emph{Add}
\item This will open the standard \emph{Open file(s)} dialog
\item Select the file(s) you want to add
\item Click \emph{Open}
\item The files will show up in the \emph{New signatures} list
\end{itemize}

At this point the files haven't been installed yet.
The databases currently installed can be seen in the \emph{Installed signatures} list.
By default you should see \verb+main.cvd+,\verb+daily.cvd+, and \verb+bytecode.cvd+
\footnote{Or .cld once they are updated. CVD files change into CLD files upon an update.
Of course if the updater didn't run yet you won't see any files there}.

You want your new signatures to show up in the \emph{Installed signatures}, so the next step is clicking on \emph{Verify and Install signatures}.
This will perform the following:
\begin{itemize}
\item Copy all the signatures to a (protected) temporary staging directory \footnote{\texttt{clamav\textbackslash staging\_dir} subdirectory}.
\item Test the signatures by loading each one\footnote{Using \texttt{libclamav.dll} only, they are not loaded in the realtime engine}. CVD files also have their digital signature checked.
\item The signatures that pass verification are installed in the real database directory
\item \CW will load them the next time it updates the database (usually once ah hour)
\item If there are signatures that fail verification an error message will be shown, with details on why the signatures failed to load.
\end{itemize}

\subsection{Removing signature files}
\label{sec:localremove}
If you want to remove one of your signatures, you can select the file in the \emph{Installed signatures} list, and click \emph{Delete}. This will erase the file from the disk!
Note that you can delete the files automatically downloaded by \gls{freshclam} too, but they will just reappear at the next update.  The only file you can't delete is \gls{daily.cvd} and \gls{daily.cld}.
The presence of one these files is essential to the proper operation of the \gls{ClamAV} engine.

\subsection{Automating signature and configuration file deployments on a network}
\label{sec:customautomatedcopy}
\label{sec:deploy_conf}

The graphical mode of SigUI is useful for making local changes to \gls{freshclam.conf} and the database directory. However if you want to automate the process (call it from a script), there is a commandline interface too:
\begin{itemize}
	\item You must run it as Administrator user. Otherwise you get the \gls{UAC} popup, which is not what you want in a script.
	\item If you want to copy signatures to the database directory:
		\begin{itemize}
			\item Create a file \verb+signatureslist+ with the full path to the signatures you want to install, one on a line. Don't quote or escape the filenames, just write them as is.
			\item Run:
\begin{lstlisting}
"C:\Program Files\ClamAV for Windows\clamav\SigUI.exe" -i <signatureslist
\end{lstlisting}
			\item Another alternative is to pipe it the output of another program \footnote{Interactively entering the filenames from the commandprompt won't work}:
\begin{lstlisting}
echo '<databasepath>' | "C:\Program Files\ClamAV for Windows\clamav\SigUI.exe" -i
\end{lstlisting}
			\item SigUI will test each database by loading them, and prints progress messages to the standard output.
			\item SigUI will print error messages on failed database loads to the standard error
			\item The exitcode will be 0 if all signatures were successfully installed, and nonzero if some signatures failed to install
		\end{itemize}
Note that using \gls{freshclam}'s support for custom signature URLs is usually a better solution, you will only need to deploy the modified \gls{freshclam.conf}.
\item Deploying a modified \gls{freshclam.conf}:

\begin{itemize}
\item Create a \gls{freshclam.conf} on one machine with \gls{SigUI}
\item Test it, see \prettyref{sec:runfreshclam}
\item Write a script to automatically invoke \verb+SigUI.exe+ on each machine on your network (for example using a logon script, or a \verb+msi+ installer)
\item Have it execute this command:
\begin{lstlisting}
"C:\Program Files\ClamAV for Windows\clamav\SigUI.exe" -w <new\_freshclam.conf
\end{lstlisting}
\item Alternatively you can pipe it the freshclam.conf:
\begin{lstlisting}
somecommand | "C:\Program Files\ClamAV for Windows\clamav\SigUI.exe" -w
\end{lstlisting}

\item SigUI will test the config file for syntactic correctness, and install it if it is valid
\end{itemize}
\end{itemize}

\section{Setting up a local mirror}
\label{sec:localmirror}

If you have a lot of ClamAV installations on your local network, then you can setup \gls{freshclam} as described in the answer for  \emph{I’m running ClamAV on a lot of clients on my local network} at \url{http://www.clamav.net/documentation.html} under the Private Mirrors section.
Once you've setup the local mirror you can configure it:
\begin{itemize}
\item Open SigUI
\item Enter the hostname, or IP address of your local mirror in the \emph{Download official signatures from mirror:} field
\item Click \emph{Save settings}
\item Click \emph{Run freshclam to test configuration}. See \prettyref{sec:runfreshclam}
\end{itemize}

Another option is to setup a caching proxy, and set ClamAV to use that. See \prettyref{sec:proxysettings}.