Taking a closer look at the quickstart guide was still on my todo
list. It's very nice! but some thoughts about structure:
- I'd switch the order of "Reading from a Trace" vs "Live Traffic"
The former seems to be the more "natural" deployment model for a
new user.
- How about moving the "Capturing As Unprivileged User" section
out of the main flow, perhaps into an appendix or even into the
FAQ and then with a link from the Quickstart guide to there. It
feels a bit distracting where it's right now; but it's actually
also something that's quite relevant outside of the concept of
"quickstarting".
- The Bro Control part:
- I think the link between running from the command-line and
using broctl doesn't become quite clear. A bit more context
upfront in the broctl section on what's it's doing and
why/when one wants to use it would be helpful.
- I'm also wondering if broctl should be discussed first, and the
command-line version afterwards and framed as "here's the bare
bones version if you want more control".
- The use should also edit networks.cfg and broctl.cfg right
away (for the latter at least point out how to change the
recipient address for mails; that's probably the most common
change).
- At the end, not only mention the help command but also link
to the broctl README.
- The checksum discussion: is that another part for the FAQ, with
a link from the Quickstart guide to there?
- The configure/customize part: per above, I think this should
also start with doing customizations via BroControl: where's the
local policy I can edit; an example of what I put there
(local_nets isn't a good one here because broctl already takes
care of that via networks.cfg); and what do I do to put the
change into place ("broctl check"; "install"; and "restart").
- $PREFIX/etc/analysis.dat isn't meant to be user-visible.
Taking these together, what I would suggest I think is to actually
have one section just on BroControl, with the corresponding parts
taken out of the current running/configuraion sections; and then a
separate section on just command-line usage. Does that make sense?
Couple further thoughts:
- Don't remember whether we talked abot this already, but
navigation links between the sections would be helpul.
- For the preview, we should add a note that binary packages won't
be available before the final release.
Robin