[Bro-Dev] Quickstart guide feedback

[Robin Sommer]

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

-- 
Robin Sommer * Phone +1 (510) 722-6541 * robin at icir.org
ICSI/LBNL    * Fax   +1 (510) 666-2956 *   www.icir.org