devguide/transactions: fix image filename

.github/workflows/builds.yml

@@ -1014,6 +1014,7 @@ jobs:
                 libjansson-dev \
                 libpython2.7 \
                 make \
+                mscgen \
                 parallel \
                 python3-yaml \
                 rustc \

configure.ac

@@ -2322,6 +2322,18 @@ fi
         AC_DEFINE([CLS],[64],[L1 cache line size])
     fi
 
+# mscgen for devguide images
+    AC_PATH_PROG([HAVE_MSCGEN], mscgen, "no")
+    if test "$HAVE_MSCGEN" = "no"; then
+        enable_mscgen=no
+        echo "WARNING! mscgen package not installed."
+        echo "    Devguide images won't be generated!"
+        echo "    Get mscgen package:"
+        echo "    https://www.mcternan.me.uk/mscgen/"
+        echo "    or install it from your distribution"
+    fi
+    AM_CONDITIONAL([HAVE_MSCGEN], [test "x$enable_mscgen" != "xno" ])
+
 # sphinx for documentation
     AC_PATH_PROG(HAVE_SPHINXBUILD, sphinx-build, "no")
     if test "$HAVE_SPHINXBUILD" = "no"; then

doc/devguide/.gitignore

@@ -1 +1,2 @@
 _build
+extending/app-layer/img/*.png

doc/devguide/Makefile.am

@@ -7,6 +7,7 @@ EXTRA_DIST = \
 	extending/index.rst \
 	extending/app-layer/index.rst \
 	extending/app-layer/parser.rst \
+	extending/app-layer/transactions.rst \
 	extending/capture/index.rst \
 	extending/output/index.rst \
 	internals/engines/index.rst \
@@ -22,6 +23,7 @@ EXTRA_DIST = \
 	codebase/fuzz-testing.rst
 
 if HAVE_SPHINXBUILD
+if HAVE_MSCGEN
 
 if HAVE_PDFLATEX
 EXTRA_DIST += devguide.pdf
@@ -30,13 +32,15 @@ endif
 SPHINX_BUILD = sphinx-build -q
 
 html:
+	$(top_srcdir)/doc/devguide/extending/app-layer/img/generate-images.sh
 	sysconfdir=$(sysconfdir) \
 	localstatedir=$(localstatedir) \
 	version=$(PACKAGE_VERSION) \
 		$(SPHINX_BUILD) -W -b html -d _build/doctrees \
 		$(top_srcdir)/doc/devguide _build/html
 
 _build/latex/Suricata.pdf:
+	$(top_srcdir)/doc/devguide/extending/app-layer/img/generate-images.sh
 	sysconfdir=$(sysconfdir) \
 	localstatedir=$(localstatedir) \
 	version=$(PACKAGE_VERSION) \
@@ -62,4 +66,5 @@ clean-local:
 	rm -f $(top_builddir)/doc/devguide/suricata.1
 	rm -f $(top_builddir)/doc/devguide/devguide.pdf
 
+endif # HAVE_MSCGEN
 endif # HAVE_SPHINXBUILD

doc/devguide/Makefile.sphinx

@@ -18,6 +18,7 @@ PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+BUILD_IMG = ./extending/app-layer/img/generate-images.sh
 
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text changes linkcheck doctest coverage gettext
 
@@ -51,37 +52,44 @@ clean:
 	rm -rf $(BUILDDIR)/*
 
 html:
+	$(BUILD_IMG)
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 dirhtml:
+	$(BUILD_IMG)
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
 singlehtml:
+	$(BUILD_IMG)
 	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
 pickle:
+	$(BUILD_IMG)
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
 json:
+	$(BUILD_IMG)
 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
 htmlhelp:
+	$(BUILD_IMG)
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in $(BUILDDIR)/htmlhelp."
 
 qthelp:
+	$(BUILD_IMG)
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
@@ -91,6 +99,7 @@ qthelp:
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Suricata.qhc"
 
 applehelp:
+	$(BUILD_IMG)
 	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
 	@echo
 	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
@@ -99,6 +108,7 @@ applehelp:
 	      "bundle."
 
 devhelp:
+	$(BUILD_IMG)
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
@@ -108,48 +118,56 @@ devhelp:
 	@echo "# devhelp"
 
 epub:
+	$(BUILD_IMG)
 	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
 latex:
+	$(BUILD_IMG)
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 	      "(use \`make latexpdf' here to do that automatically)."
 
 latexpdf:
+	$(BUILD_IMG)
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through pdflatex..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
 latexpdfja:
+	$(BUILD_IMG)
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through platex and dvipdfmx..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
 text:
+	$(BUILD_IMG)
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
 	@echo
 	@echo "Build finished. The text files are in $(BUILDDIR)/text."
 
 texinfo:
+	$(BUILD_IMG)
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo
 	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
 	@echo "Run \`make' in that directory to run these through makeinfo" \
 	      "(use \`make info' here to do that automatically)."
 
 info:
+	$(BUILD_IMG)
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo "Running Texinfo files through makeinfo..."
 	make -C $(BUILDDIR)/texinfo info
 	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
 
 gettext:
+	$(BUILD_IMG)
 	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
 	@echo
 	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."

doc/devguide/extending/app-layer/img/DnsRequestUnidirectionalTransaction.msc

@@ -0,0 +1,13 @@
+# MSC Sequence Diagram Example: DNS Query Transaction
+
+msc {
+    # Chart Options
+    arcgradient = "10";
+
+    # Entities
+    a [ label = "Client" ], b [ label = "Server" ];
+
+    # Message Flow
+    a =>> b [ label = "DNS Request" ];
+    --- [ label = "Transaction Completed" ];
+}

doc/devguide/extending/app-layer/img/HTTP2BidirectionalTransaction.msc

@@ -0,0 +1,18 @@
+# MSC Sequence Diagram for an HTTP2 Transaction, which is bidirectional in Suricata
+
+msc {
+
+    # Chart options
+    arcgradient = "10";
+
+    # Entities
+    a [ label = "Client" ], b [ label = "Server" ];
+
+    # Message flow
+    a =>> b [ label = "Request" ];
+    b =>> a [ label = "Response" ];
+    |||;
+    --- [ label = "Transaction Completed" ];
+}
+
+# Reference: https://tools.ietf.org/html/rfc7540#section-8.1

doc/devguide/extending/app-layer/img/TemplateTransaction.msc

@@ -0,0 +1,15 @@
+# MSC Sequence Diagram Example: Template transaction
+
+msc {
+    # Chart Options
+    arcgradient = "10";
+
+    # Entities
+    a [ label = "Client" ], b [ label = "Server" ];
+
+    # Message Flow
+    a =>> b [ label = "Request ('12:HelloWorld!')" ];
+    b =>> a [ label = "Response ('3:Bye')" ];
+    |||;
+    --- [ label = "Transaction Completed" ];
+}

doc/devguide/extending/app-layer/img/TlsHandshake.msc

@@ -0,0 +1,21 @@
+# MSC Sequence Diagram Example: TLS Handshake Transaction
+
+msc {
+    # Chart Options
+    arcgradient = "10";
+
+    # Entities
+    a [ label = "Client" ], b [ label = "Server"];
+
+    # Message Flow
+    a =>> b [ label = "ClientHello"];
+    b =>> a [ label = "ServerHello"];
+    b =>> a [ label = "ServerCertificate"];
+    b =>> a [ label = "ServerHello Done"];
+    a =>> b [ label = "ClientCertificate"];
+    a =>> b [ label = "ClientKeyExchange"];
+    a =>> b [ label = "Finished" ];
+    b =>> a [ label = "Finished" ];
+
+    --- [ label = "Transaction Completed" ];
+}

doc/devguide/extending/app-layer/img/generate-images.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+#
+# Script to generate Sequence Diagram images with mscgen
+#
+
+cd extending/app-layer/img
+
+for FILE in *.msc ; do
+    # call mscgen and convert each file in images dir
+    mscgen -T png -F Arial $FILE
+    # if command fails, lets inform about that
+    if [ $? -ne 0 ]; then
+        echo "$FILE couldn't be converted in the devguide"
+    fi
+done
+
+exit 0

doc/devguide/extending/app-layer/index.rst

@@ -5,3 +5,4 @@ App-Layer
    :maxdepth: 2
 
    parser.rst
+   transactions.rst