## Usage

### Select a vhost/conf


 * Selects which config file will be shown and edited.
 * Will change the status icons shown next to the rules, if anything is configured in that vhost/conf file.


 * And <kbd>Disable</kbd> or <kbd>Enable</kbd> will influence that very rule state.
 * Browse for high error counts to check on rules which ***might*** be false positives.
 * Verify what the rules do with the <kbd>Info</kbd> dialog.

![info](info.png)

 * Take particular note to the recent log entries there. Recent events will give
   a clue if a rule really blocked concrete intrusion attempts, or expected requests.


### Select log file to show

 * Switching vhosts should automatically select the according log file.
   Else use the dropdown box:

![log](log.png)

 * For rule scoring it's best to use the error.log.
 * Audit.logs take much longer to process. (In particular non-JSON audit logs,
   or reading concurrent/directory-stored ones.)
 * Browse through the entries to see more detail in the logview box:

![logview](logview.png)

 * Use the search feature above the log dropdown to filter events by common messages.

 * See also [<kbd>Log</kbd> → <kbd>Reports</kbd> /

![logfilter](logfilter.png)

 * A handful of common log errors are explained via <kbd>Log</kbd> → <kbd>Advise</kbd>


### Install

 * There's a few packages/scripts in <kbd>File</kbd> → <kbd>Install</kbd>
 * Any entry will bring up a "terminal" prompt before excuting the commands.
 * Notably the installation will work on remote servers. If you want to apply the
   same package locally, you might need to restart modseccfg without [remoting](wiki/remoting).


### <kbd>File</kbd> → <kbd>Settings</kbd>


There's a few notable options for modseccfg itself, that change default behaviours
and even how config files are updated.

 * Most notably the backup options (albeit there are failsafes, it's still beta software).
 * Or where to mount remote filesystems.
 * And how to filter logs.


### <kbd>File</kbd> → <kbd>SecOptions</kbd>

This dialog updates core mod_security directives. Most of those you want to change
in the global mod_security.conf (selected as vhost/conf), or a customized
if you have such.

But you can of course change these directives on a per-vhost basis. Most notably
SecRuleEngine to DetectionOnly whilst testing the rules.

Note that each option will yield a lengthier tooltip explanation.


### <kbd>File</kbd> → <kbd>CoreRuleSet options</kbd>

The CoreRuleSet comes with its own set of runtime variables (tx.varname). Generally
you want to edit the crs-setup.conf file globally, if possible.

Some vhosts might need customized handling however. And this is where it gets complicated.
You will need [preconf](wiki/preconf) enabled. And keep in mind that you'll be preempting
setvar: expressions from crs-setup.conf. Which is why the dialog offers an "id" and a
"fn" option atop.
When overriding variables, the according entry from crs-setup needs to be stopped from
running (because it's executed after the *.preconf rule). Hence the CRS options dialog
will usually use id:5999 and a ctl:removeRule= list for each variable.

However, when invoking the dialog on a freshly created preconf file, all the
usual fields will be empty.  That's ok for boolean and numberic flags, which are quick
to fill in.  But the tx.allowed_request_content_types for example requires appending
on the original list.

 * So, you either want to use an text editor in parallel for the long fields,
 * Or temporarily enable <kbd>Settings</kbd> → CRS options → use defaults to have
   them filled with standard values.
 * Or select the global crs-setup.conf as vhost/conf first, then start the CRS options
   dialog, and set "id" to 5999 and "fn" to the vhost.*.preconf file you actually want
   to update.

So the dialog is more of a gimmick here. Editing crs-setup.conf directly is often more
practical, unless there are stark contrasts between vhosts.


### Recipes

See also [recipe](wiki/recipe) on other/conditional SecRule* constructs to control
rules.


### Editor

F4 will bring up the .conf file editor. Because some things are best handled with
a keyboard after all.

And F3 will show the editor (in read-only mode) for the current log file instead.