summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorYasufumi Ogawa <yasufum.o@gmail.com>2019-09-02 17:34:18 +0900
committerYasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>2019-09-10 17:49:31 +0900
commitbbd1ea3b07d74c6f3b640a96c2b2b243e68c1551 (patch)
tree9cb6ecfa74b137ed5e3c35c69bf96c6a878d4169
parentd769f4ed7e8149496a579d2dcfe73a461655bea7 (diff)
downloadspp-bbd1ea3b07d74c6f3b640a96c2b2b243e68c1551.zip
spp-bbd1ea3b07d74c6f3b640a96c2b2b243e68c1551.tar.gz
spp-bbd1ea3b07d74c6f3b640a96c2b2b243e68c1551.tar.xz
docs: add suricata in sppc
This update is to add build and howto use section for suricata in SPP container. Signed-off-by: Yasufumi Ogawa <yasufum.o@gmail.com>
-rw-r--r--docs/guides/tools/sppc/app_launcher.rst60
-rw-r--r--docs/guides/tools/sppc/build_img.rst84
2 files changed, 134 insertions, 10 deletions
diff --git a/docs/guides/tools/sppc/app_launcher.rst b/docs/guides/tools/sppc/app_launcher.rst
index ae960c2..f89dbdf 100644
--- a/docs/guides/tools/sppc/app_launcher.rst
+++ b/docs/guides/tools/sppc/app_launcher.rst
@@ -1098,7 +1098,6 @@ or failed to launch.
--lpm "1.0.0.0/24=>0; 1.0.1.0/24=>1; 1.0.2.0/24=>2;"
-``load-balancer.py`` supports all of options other than mandatories.
Refer options and usages by ``load-balancer.py -h``.
.. code-block:: console
@@ -1144,6 +1143,65 @@ Refer options and usages by ``load-balancer.py -h``.
...
+.. _sppc_appl_suricata:
+
+Suricata Container
+------------------
+
+`Suricata
+<https://suricata.readthedocs.io/en/suricata-4.1.2/index.html>`_
+is a sophisticated IDS/IPS application.
+SPP container supports suricata 4.1.4 hosted this
+`repository
+<https://github.com/vipinpv85/DPDK_SURICATA-4_1_1>`_.
+
+Unlike other scripts, ``app/suricata.py`` does not launch appliation
+directly but bash to enable to edit config file on the container.
+Suricata accepts options from config file specified with
+``--dpdk`` option.
+You can copy your config to the container by using ``docker cp``.
+Sample config ``mysuricata.cfg`` is included under ``suricata-4.1.4``.
+
+Here is an example of launching suricata with image
+``sppc/suricata-ubuntu2:latest``
+which is built as described in
+:ref:`sppc_build_img_suricata`.
+
+.. code-block:: console
+
+ $ docker cp your.cnf CONTAINER_ID:/path/to/conf/your.conf
+ $ ./suricata.py -d 1,2 -fg -ci sppc/suricata-ubuntu2:latest
+ # suricata --dpdk=/path/to/config
+
+
+Refer options and usages by ``load-balancer.py -h``.
+
+.. code-block:: console
+
+ $ python app/suricata.py -h
+ usage: suricata.py [-h] [-l CORE_LIST] [-c CORE_MASK] [-m MEM]
+ [--socket-mem SOCKET_MEM]
+ [-b [PCI_BLACKLIST [PCI_BLACKLIST ...]]]
+ [-w [PCI_WHITELIST [PCI_WHITELIST ...]]]
+ [--single-file-segments] [--nof-memchan NOF_MEMCHAN]
+ [-d DEV_IDS] [-nq NOF_QUEUES] [--no-privileged]
+ [--dist-name DIST_NAME] [--dist-ver DIST_VER]
+ [--workdir WORKDIR] [-ci CONTAINER_IMAGE] [-fg] [--dry-run]
+
+ Launcher for suricata container
+
+ optional arguments:
+ ...
+ -d DEV_IDS, --dev-ids DEV_IDS
+ two or more even vhost device IDs
+ -nq NOF_QUEUES, --nof-queues NOF_QUEUES
+ Number of queues of virtio (default is 1)
+ --no-privileged Disable docker's privileged mode if it's needed
+ --dist-name DIST_NAME
+ Name of Linux distribution
+ ...
+
+
.. _sppc_appl_helloworld:
Helloworld Container
diff --git a/docs/guides/tools/sppc/build_img.rst b/docs/guides/tools/sppc/build_img.rst
index b06c9dd..9f74ac7 100644
--- a/docs/guides/tools/sppc/build_img.rst
+++ b/docs/guides/tools/sppc/build_img.rst
@@ -14,12 +14,12 @@ This script is for running ``docker build`` with a set of
This script supports building application from any of repositories.
For example, you can build SPP hosted on your repository
``https://github.com/your/spp.git``
-with DPDK 18.02 as following.
+with DPDK 18.11 as following.
.. code-block:: console
$ cd /path/to/spp/tools/sppc
- $ python build/build.py --dpdk-branch v18.02 \
+ $ python build/build.py --dpdk-branch v18.11 \
--spp-repo https://github.com/your/spp.git
Refer all of options running with ``-h`` option.
@@ -28,18 +28,20 @@ Refer all of options running with ``-h`` option.
$ python build/main.py -h
usage: main.py [-h] [-t TARGET] [-ci CONTAINER_IMAGE]
- [--dist-name DIST_NAME]
- [--dist-ver DIST_VER] [--dpdk-repo DPDK_REPO]
- [--dpdk-branch DPDK_BRANCH] [--pktgen-repo PKTGEN_REPO]
- [--pktgen-branch PKTGEN_BRANCH] [--spp-repo SPP_REPO]
- [--spp-branch SPP_BRANCH] [--only-envsh] [--dry-run]
+ [--dist-name DIST_NAME] [--dist-ver DIST_VER]
+ [--dpdk-repo DPDK_REPO] [--dpdk-branch DPDK_BRANCH]
+ [--pktgen-repo PKTGEN_REPO] [--pktgen-branch PKTGEN_BRANCH]
+ [--spp-repo SPP_REPO] [--spp-branch SPP_BRANCH]
+ [--suricata-repo SURICATA_REPO]
+ [--suricata-branch SURICATA_BRANCH]
+ [--only-envsh] [--dry-run]
Docker image builder for DPDK applications
optional arguments:
-h, --help show this help message and exit
-t TARGET, --target TARGET
- Build target ('dpdk', 'pktgen' or 'spp')
+ Build target ('dpdk', 'pktgen', 'spp' or 'suricata')
-ci CONTAINER_IMAGE, --container-image CONTAINER_IMAGE
Name of container image
--dist-name DIST_NAME
@@ -56,6 +58,10 @@ Refer all of options running with ``-h`` option.
--spp-repo SPP_REPO Git URL of SPP
--spp-branch SPP_BRANCH
Specific version or branch of SPP
+ --suricata-repo SURICATA_REPO
+ Git URL of DPDK-Suricata
+ --suricata-branch SURICATA_BRANCH
+ Specific version or branch of DPDK-Suricata
--only-envsh Create config 'env.sh' and exit without docker build
--dry-run Print matrix for checking and exit without docker
build
@@ -151,12 +157,72 @@ It is included in a future release.
| |--- Dockerfile.16.04
| |--- Dockerfile.18.04
| ---- Dockerfile.latest
- ---- spp
+ |--- spp
+ | |--- Dockerfile.16.04
+ | |--- Dockerfile.18.04
+ | ---- Dockerfile.latest
+ ---- suricata
|--- Dockerfile.16.04
|--- Dockerfile.18.04
---- Dockerfile.latest
+.. _sppc_build_img_suricata:
+
+Build suricata image
+~~~~~~~~~~~~~~~~~~~~
+
+Building DPDK, pktgen and SPP is completed by just running ``build/main.py``
+script. However, building suricata requires few additional few steps.
+
+
+First, build an image with ``main.py`` script as similar to other apps.
+In this example, use DPDK v18.11 and Ubuntu 16.04.
+
+.. code-block:: console
+
+ $ python build/main.py -t suricata --dpdk-branch v18.11 --dist-ver 16.04
+
+After build is completed, you can find image named as
+``sppc/suricata-ubuntu:16.04`` from ``docker images``.
+Run bash command with this image, and execute an installer script in home
+directory which is created while building.
+
+.. code-block:: console
+
+ sppc/suricata-ubuntu 16.04 ...
+ $ docker run -it sppc/suricata-ubuntu:16.04 /bin/bash
+ # ./install_suricata.sh
+
+It clones and compiles suricata under home directory. You can find
+``$HOME/DPDK_SURICATA-4_1_1`` after runing this script is completed.
+
+Although now you are ready to use suricata, it takes a little time for doing
+this task everytime you run the app container.
+For skipping this task, you can create another image from running container
+with ``docker commit`` command.
+
+Logout and create a new docker image with ``docker commit`` image's
+container ID. In this example, new image is named as
+`sppc/suricata-ubuntu2:16.04`.
+
+.. code-block:: console
+
+ # exit
+ $ docker ps -a
+ CONTAINER_ID sppc/suricata-ubuntu:16.04 "/bin/bash" 3 minutes ...
+ $ docker commit CONTAINER_ID sppc/suricata-ubuntu2:16.04
+
+You can run compiled suricata with the new image with docker as following,
+or app container launcher with specific options as described in.
+:ref:`sppc_appl_suricata`.
+
+.. code-block:: console
+
+ $ docker run -it sppc/suricata-ubuntu:16.04 /bin/bash
+ # suricata --build-info
+
+
.. _sppc_build_img_inspect:
Inspect Inside of Container