From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id DC00DA00E6 for ; Mon, 2 Sep 2019 10:34:24 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id A338B1D505; Mon, 2 Sep 2019 10:34:24 +0200 (CEST) Received: from mail-pg1-f179.google.com (mail-pg1-f179.google.com [209.85.215.179]) by dpdk.org (Postfix) with ESMTP id D63C81D505 for ; Mon, 2 Sep 2019 10:34:23 +0200 (CEST) Received: by mail-pg1-f179.google.com with SMTP id d10so2571114pgo.5 for ; Mon, 02 Sep 2019 01:34:23 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:subject:date:message-id; bh=bjlzfqyccqe4wFzWF7pj3WUVxxkxuwZNRWboY8aRw4g=; b=PtekBFtloDBp4V+HX2jGcLC5QBXmQ/rPQmKTkCLjrYvOH78ifWpcq43N9MA103d8YW SZTB0YRE5QpeEN3xrYtjhsJsi/xVZWoUoVVZoo1X09Nu7oroYAujnu6zgejvQHTSFQrz V9uyg96xwnNZqEapGaTuUPXX4jhChcsFgKCHGxvMMdwvi9hAkdZpD7gvxfXhH5BJgok7 9tl5iequpYfT0mWPzRdVMteV4hQmCyk0VtuZJGyBVu+PTJDpyO6vi6ETdAem2hpxjEAy UzeSj+jegk4lsOLgS6x0AsSlFe1w7juAGWMYyct6zs8yUTw/DYrRC1udRFJB79OQbo2O XG2g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:date:message-id; bh=bjlzfqyccqe4wFzWF7pj3WUVxxkxuwZNRWboY8aRw4g=; b=t7lD9rTODEoKQmPjjsyBykZ4zwFpvPAKIyc7mZrpAw4C+QjkpZvBb03IUZItlr7q8V O28GoAr6QD+QKG0eQe/SGbomGJBOdBdTTlAsR8SeU7BrEz/avClozGr3ZYKOLhbzd5Bu 9indU0g4FIfNYN8CCL5kGJxdjERjL+9eDm8PjsZ5J1xlu/XKm0QI6l6KUduRhAGvrzi4 n7udQznF6JrHCz8RycGq/JBIXE+9wahud5wgj1wl1VaMi0rSYDLTctAO2gKZrsZFShaY N/tEfAeNn+OG2n3OqW3peFUKqXyTK9dD39jHvLyL8kFvfdGrJuZFHj0LoHQ4VQfSVc5S 7aAA== X-Gm-Message-State: APjAAAV/8LjLtcIYUBnyBaJ2fnZAl/fn9HjC05CHOE1fZKESBiat2+zS s22fWPgS8pIaU0WG8ajFrlERBqEe X-Google-Smtp-Source: APXvYqynMsDpyivlD9+xC6pj+ZDYLWpRQgPVJHFwizF4zSWu38T3xHzS4AliNY20/1PzpQV8PdLUVQ== X-Received: by 2002:a05:6a00:c7:: with SMTP id e7mr32867839pfj.52.1567413262673; Mon, 02 Sep 2019 01:34:22 -0700 (PDT) Received: from localhost.localdomain ([2400:4050:c8c2:de00:c8a6:53f8:f102:d617]) by smtp.gmail.com with ESMTPSA id h4sm4021866pfg.159.2019.09.02.01.34.21 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 02 Sep 2019 01:34:22 -0700 (PDT) From: Yasufumi Ogawa To: spp@dpdk.org, ferruh.yigit@intel.com, yasufum.o@gmail.com Date: Mon, 2 Sep 2019 17:34:18 +0900 Message-Id: <20190902083418.13108-1-yasufum.o@gmail.com> X-Mailer: git-send-email 2.17.1 Subject: [spp] [PATCH] docs: add suricata in sppc X-BeenThere: spp@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: Soft Patch Panel List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: spp-bounces@dpdk.org Sender: "spp" This update is to add build and howto use section for suricata in SPP container. Signed-off-by: Yasufumi Ogawa --- docs/guides/tools/sppc/app_launcher.rst | 60 +++++++++++++++++- docs/guides/tools/sppc/build_img.rst | 84 ++++++++++++++++++++++--- 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 01bf722..5aa4349 100644 --- a/docs/guides/tools/sppc/app_launcher.rst +++ b/docs/guides/tools/sppc/app_launcher.rst @@ -1086,7 +1086,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 @@ -1132,6 +1131,65 @@ Refer options and usages by ``load-balancer.py -h``. ... +.. _sppc_appl_suricata: + +Suricata Container +------------------ + +`Suricata +`_ +is a sophisticated IDS/IPS application. +SPP container supports suricata 4.1.4 hosted this +`repository +`_. + +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 -- 2.17.1