Bro 2.4.1 documentation

Hi all,

I am reading through Bro’s documentation for a variety of purposes, I am new to it and really want to understand the internals, the scripting language, scaling up for clustering for larger link monitoring etc.

I find the websites layout not that good for reading as I am reading a book about any other open source project I read about. Other open source security projects I read about have PDFs versions of their documentation so people can print it out etc.

Is the same thing available for Bro? Have copied all of the doco into a word document but cancelled that as formatting was ugly. The only mention of Bro in a book I have found is a couple pages long. I’d like the entire documentation available for whatever latest release but as PDF.

Anyone else know where to find it? Or if it’s even available?

Thanks,
John

Hi John,

the Bro documentation is currently not available in any format besides
html, sorry.

Johanna

As Johanna said it isn't published anywhere, but the tool that builds all the documentation (sphinx) can easily build a single page document. The only reason it doesn't is that doc/CMakeLists.txt only runs sphinx-build with -b html.

I re-ran it with -b singlehtml, and it worked but the output is a little unwieldy and the formatting could be better. This can probably be fixed with a few lines of css though.

-b latex works, but then pdflatex isn't happy with rendering the resulting file. The OS X book reader doesn't like the .epub files that -b epub builds.

However, I did have good success using 'sphinx-build -b man' and then 'man -Tpdf ./bro.1 > bro.pdf'

That outputs this:

http://www.ncsa.illinois.edu/People/jazoff/bro-2.4.1.pdf

Which is pretty close. The ToC items aren't links and images are missing, but that's probably the most reader friendly so far.

Correct.. the pdf export is generated via the latex output. I can generate the Bro.tex file, but wasn't able to get pdflatex to work last night.

Trying to run pdflatex on it first gives memory errors, but doing

export extra_mem_bot=18000000

gets past that, but it has more issues:

(/usr/local/texlive/2016/texmf-dist/tex/latex/psnfss/ts1pcr.fd)
! Dimension too large.
\fb@put@frame ...p \ifdim \dimen@ >\ht \@tempboxa
                                                  \fb@putboxa #1\fb@afterfra...
l.19029 \end{Verbatim}
?

Now that I'm not super tired, I figured out I can just type R at that prompt and it completes after that.

There's probably some table or figure that is missing from the output, but otherwise the result looks good.

I replaced http://www.ncsa.illinois.edu/People/jazoff/bro-2.4.1.pdf with this new output. The latex -> pdf output is much nicer than the man -> pdf output. In addition to the links working, the images are included.

It looks like it could still use some tweaks. I think the main thing is that the ToC needs to show one more sub level to break up each of the sections further. I tried changing the index.rst to have

.. toctree::
   :maxdepth: 3

instead of 2 but that didn't seem to do anything. The docs has a note that "The LaTeX writer only refers the maxdepth option of first toctree directive in the document." but the one in index.rst should be the first.