From cb1b4e93c93b1c2e4de15180c7b06b78fcdf5a8e Mon Sep 17 00:00:00 2001 From: Toby McLaughlin Date: Fri, 12 May 2017 14:29:33 +1000 Subject: [PATCH] Add docs for Docker images --- filebeat/docs/getting-started.asciidoc | 49 ++++++++------- filebeat/docs/index.asciidoc | 3 + filebeat/docs/running-on-docker.asciidoc | 1 + heartbeat/docs/getting-started.asciidoc | 41 +++++++------ heartbeat/docs/index.asciidoc | 5 +- heartbeat/docs/running-on-docker.asciidoc | 1 + libbeat/docs/dashboards.asciidoc | 23 ++++--- libbeat/docs/shared-configuring.asciidoc | 10 +++ libbeat/docs/shared-directory-layout.asciidoc | 14 ++++- libbeat/docs/shared-docker.asciidoc | 61 +++++++++++++++++++ .../docs/shared-download-and-install.asciidoc | 13 ++++ libbeat/docs/shared-template-load.asciidoc | 7 +++ metricbeat/docs/gettingstarted.asciidoc | 52 ++++++++-------- metricbeat/docs/index.asciidoc | 5 +- ...er.asciidoc => running-on-docker.asciidoc} | 57 +++++++---------- packetbeat/docs/gettingstarted.asciidoc | 47 ++++++++------ packetbeat/docs/index.asciidoc | 3 + packetbeat/docs/running-on-docker.asciidoc | 29 +++++++++ 18 files changed, 288 insertions(+), 133 deletions(-) create mode 100644 filebeat/docs/running-on-docker.asciidoc create mode 100644 heartbeat/docs/running-on-docker.asciidoc create mode 100644 libbeat/docs/shared-configuring.asciidoc create mode 100644 libbeat/docs/shared-docker.asciidoc create mode 100644 libbeat/docs/shared-download-and-install.asciidoc rename metricbeat/docs/{metricbeat-in-a-container.asciidoc => running-on-docker.asciidoc} (69%) create mode 100644 packetbeat/docs/running-on-docker.asciidoc diff --git a/filebeat/docs/getting-started.asciidoc b/filebeat/docs/getting-started.asciidoc index 3c8ba64ab69..573144f41c4 100644 --- a/filebeat/docs/getting-started.asciidoc +++ b/filebeat/docs/getting-started.asciidoc @@ -27,17 +27,7 @@ After installing the Elastic Stack, read the following topics to learn how to in Before running Filebeat, you need to install and configure the Elastic stack. See {libbeat}/getting-started.html[Getting Started with Beats and the Elastic Stack]. -To download and install Filebeat, use the commands that work with your system -(<> for Debian/Ubuntu, <> for Redhat/Centos/Fedora, <> for OS X, and <> for Windows). - -[NOTE] -================================================== -If you use Apt or Yum, you can <> to update to the newest version more easily. - -See our https://www.elastic.co/downloads/beats/filebeat[download page] for other installation options, such as 32-bit images. - -================================================== +include::../../libbeat/docs/shared-download-and-install.asciidoc[] [[deb]] *deb:* @@ -96,6 +86,24 @@ tar xzvf filebeat-{version}-darwin-x86_64.tar.gz endif::[] +[[docker]] +*docker:* + +ifeval::["{release-state}"=="unreleased"] + +Version {stack-version} of {beatname_uc} has not yet been released. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +["source", "shell", subs="attributes"] +------------------------------------------------ +docker pull {dockerimage} +------------------------------------------------ + +endif::[] + [[win]] *win:* @@ -137,17 +145,9 @@ started experience for common log formats. See <> to learn how to get started with modules. If you use Filebeat modules to get started, you can skip the content in this section, including the remaining getting started steps, and go directly to the <> -page. +page. -To configure Filebeat manually, you edit the configuration file. For rpm and deb, -you'll find the configuration file at `/etc/filebeat/filebeat.yml`. For mac and -win, look in the archive that you just extracted. There’s also a full example -configuration file called `filebeat.full.yml` that shows all non-deprecated -options. - -See the -{libbeat}/config-file-format.html[Config File Format] section of the -_Beats Platform Reference_ for more about the structure of the config file. +include::../../libbeat/docs/shared-configuring.asciidoc[] Here is a sample of the `filebeat` section of the `filebeat.yml` file. Filebeat uses predefined default values for most configuration options. @@ -240,6 +240,13 @@ sudo /etc/init.d/filebeat start sudo /etc/init.d/filebeat start ---------------------------------------------------------------------- +*docker:* + +["source", "shell", subs="attributes"] +---------------------------------------------------------------------- +docker run {dockerimage} +---------------------------------------------------------------------- + *mac:* [source,shell] diff --git a/filebeat/docs/index.asciidoc b/filebeat/docs/index.asciidoc index 3be3f55342f..f48334e09c5 100644 --- a/filebeat/docs/index.asciidoc +++ b/filebeat/docs/index.asciidoc @@ -16,6 +16,7 @@ include::../../libbeat/docs/version.asciidoc[] :beatname_lc: filebeat :beatname_uc: Filebeat :security: X-Pack Security +:dockerimage: docker.elastic.co/beats/{beatname_lc}:{version} include::./overview.asciidoc[] @@ -31,6 +32,8 @@ include::../../libbeat/docs/shared-directory-layout.asciidoc[] include::../../libbeat/docs/repositories.asciidoc[] +include::./running-on-docker.asciidoc[] + include::./upgrading.asciidoc[] include::./how-filebeat-works.asciidoc[] diff --git a/filebeat/docs/running-on-docker.asciidoc b/filebeat/docs/running-on-docker.asciidoc new file mode 100644 index 00000000000..6bbc976ad85 --- /dev/null +++ b/filebeat/docs/running-on-docker.asciidoc @@ -0,0 +1 @@ +include::../../libbeat/docs/shared-docker.asciidoc[] diff --git a/heartbeat/docs/getting-started.asciidoc b/heartbeat/docs/getting-started.asciidoc index c319a6f7b0f..fecac45b4f3 100644 --- a/heartbeat/docs/getting-started.asciidoc +++ b/heartbeat/docs/getting-started.asciidoc @@ -32,17 +32,7 @@ monitor are running. //TODO: Add a separate topic that explores deployment scenarios in more detail (like installing on a sub-network where there's a firewall etc. -To download and install Heartbeat, use the commands that work with your -system (<> for Debian/Ubuntu, <> for Redhat/Centos/Fedora, -<> for OS X, and <> for Windows). - -[NOTE] -================================================== -If you use Apt or Yum, you can <> to update to the newest version more easily. - -See our https://www.elastic.co/downloads/beats/heartbeat[download page] for other installation options, such as 32-bit images. - -================================================== +include::../../libbeat/docs/shared-download-and-install.asciidoc[] [[deb]] *deb:* @@ -101,6 +91,25 @@ tar xzvf heartbeat-{version}-darwin-x86_64.tar.gz endif::[] + +[[docker]] +*docker:* + +ifeval::["{release-state}"=="unreleased"] + +Version {stack-version} of {beatname_uc} has not yet been released. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +["source", "shell", subs="attributes"] +------------------------------------------------ +docker pull {dockerimage} +------------------------------------------------ + +endif::[] + [[win]] *win:* @@ -147,15 +156,7 @@ options, see <>. [[heartbeat-configuration]] === Step 2: Configuring Heartbeat -To configure Heartbeat, you edit the configuration file. For rpm and deb, -you'll find the configuration file at +/etc/heartbeat/heartbeat.yml+. -For mac and win, look in the archive that you just extracted. There’s also a -full example configuration file called `heartbeat.full.yml` that shows all -non-deprecated options. - -See the -{libbeat}/config-file-format.html[Config File Format] section of the -_Beats Platform Reference_ for more about the structure of the config file. +include::../../libbeat/docs/shared-configuring.asciidoc[] Heartbeat provides monitors to check the status of hosts at set intervals. You configure each monitor individually. Heartbeat currently provides monitors diff --git a/heartbeat/docs/index.asciidoc b/heartbeat/docs/index.asciidoc index 736a7079d37..22f048a7eac 100644 --- a/heartbeat/docs/index.asciidoc +++ b/heartbeat/docs/index.asciidoc @@ -16,6 +16,7 @@ include::../../libbeat/docs/version.asciidoc[] :beatname_lc: heartbeat :beatname_uc: Heartbeat :security: X-Pack Security +:dockerimage: docker.elastic.co/beats/{beatname_lc}:{version} include::./overview.asciidoc[] @@ -29,6 +30,8 @@ include::../../libbeat/docs/shared-directory-layout.asciidoc[] include::../../libbeat/docs/repositories.asciidoc[] +include::./running-on-docker.asciidoc[] + // //include::./upgrading.asciidoc[] @@ -60,5 +63,5 @@ include::./troubleshooting.asciidoc[] include::./faq.asciidoc[] -// +// //include::./heartbeat-devguide.asciidoc[] diff --git a/heartbeat/docs/running-on-docker.asciidoc b/heartbeat/docs/running-on-docker.asciidoc new file mode 100644 index 00000000000..6bbc976ad85 --- /dev/null +++ b/heartbeat/docs/running-on-docker.asciidoc @@ -0,0 +1 @@ +include::../../libbeat/docs/shared-docker.asciidoc[] diff --git a/libbeat/docs/dashboards.asciidoc b/libbeat/docs/dashboards.asciidoc index 05c72909f1e..61ae8266d79 100644 --- a/libbeat/docs/dashboards.asciidoc +++ b/libbeat/docs/dashboards.asciidoc @@ -16,7 +16,7 @@ {beatname_uc} comes packaged with the `scripts/import_dashboards` script that you can use to import the example dashboards, visualizations, and searches for {beatname_uc}. The script also creates an index pattern, -+{beatname_lc}-*+, for {beatname_uc}. ++{beatname_lc}-*+, for {beatname_uc}. The steps in this section show how to import {beatname_uc} dashboards. You may want to import dashboards for more than one Beat or specify import options that aren't described here. See {beatsdevguide}/import-dashboards.html[Importing Existing Beat Dashboards] @@ -28,21 +28,28 @@ ifdef::allplatforms[] *deb, rpm, and mac:* -From the directory where you installed {beatname_uc}, run the `import_dashboards` script. +From the directory where you installed {beatname_uc}, run the `import_dashboards` script. ["source","sh",subs="attributes,callouts"] ---------------------------------------------------------------------- ./scripts/import_dashboards ---------------------------------------------------------------------- -On deb and rpm, the `scripts` folder is located under the home path, which is +/usr/share/{beatname_lc}/+ unless you change it. +*docker:* + +["source","sh",subs="attributes"] +---------------------------------------------------------------------- +docker run {dockerimage} ./scripts/import_dashboards +---------------------------------------------------------------------- + +On deb, rpm, and docker, the `scripts` folder is located under the home path, which is +/usr/share/{beatname_lc}/+ unless you change it. By default, the script assumes that you are running Elasticsearch on `127.0.0.1:9200`. Use the `-es` option -to specify a different location. For example: +to specify a different location. For example: ["source","sh",subs="attributes,callouts"] ---------------------------------------------------------------------- -./scripts/import_dashboards -es http://192.168.33.60:9200 +./scripts/import_dashboards -es http://192.168.33.60:9200 ---------------------------------------------------------------------- Use the `-user` option to specify the username and password to use for Elasticsearch authentication. There are a few ways to pass @@ -51,7 +58,7 @@ in the username and password. For example: ["source","sh",subs="attributes,callouts"] ----------------------------------------------------------------------- ./scripts/import_dashboards -es https://xyz.found.io -user user -pass password <1> -./scripts/import_dashboards -es https://xyz.found.io -user admin -pass $(cat ~/pass-file) <2> +./scripts/import_dashboards -es https://xyz.found.io -user admin -pass $(cat ~/pass-file) <2> ----------------------------------------------------------------------- <1> Specify the username and password as options. @@ -63,7 +70,7 @@ endif::allplatforms[] Open a PowerShell prompt as an Administrator (right-click the PowerShell icon and select *Run As Administrator*). If you are running Windows XP, you may need -to download and install PowerShell. +to download and install PowerShell. From the PowerShell prompt, change to the directory where you installed {beatname_uc}, and run the `import_dashboards.exe` script: @@ -103,7 +110,7 @@ pattern is selected to see {beatname_uc} data. image:./images/kibana-created-indexes.png[Discover tab with index selected] To open the loaded dashboards, go to the *Dashboard* page and select the -dashboard that you want to open. +dashboard that you want to open. image:./images/kibana-navigation-vis.png[Navigation widget in Kibana] diff --git a/libbeat/docs/shared-configuring.asciidoc b/libbeat/docs/shared-configuring.asciidoc new file mode 100644 index 00000000000..265bbc2b546 --- /dev/null +++ b/libbeat/docs/shared-configuring.asciidoc @@ -0,0 +1,10 @@ +To configure {beatname_uc}, you edit the configuration file. For rpm and deb, +you'll find the configuration file at +/etc/{beatname_lc}/{beatname_lc}.yml+. Under +Docker, it's located at +/usr/share/{beatname_lc}/{beatname_lc}.yml+. For mac and win, +look in the archive that you just extracted. There’s also a full example +configuration file called +{beatname_lc}.full.yml+ that shows all non-deprecated +options. + +See the +{libbeat}/config-file-format.html[Config File Format] section of the +_Beats Platform Reference_ for more about the structure of the config file. diff --git a/libbeat/docs/shared-directory-layout.asciidoc b/libbeat/docs/shared-directory-layout.asciidoc index 1ff50002f86..eb6b7684f54 100644 --- a/libbeat/docs/shared-directory-layout.asciidoc +++ b/libbeat/docs/shared-directory-layout.asciidoc @@ -29,7 +29,7 @@ file. ==== Default paths -{beatname_uc} uses the following default paths unless you explicitly change them. +{beatname_uc} uses the following default paths unless you explicitly change them. [float] ===== deb and rpm @@ -48,6 +48,18 @@ the systemd unit file. Make sure that you start the {beatname_uc} service by us the preferred operating system method (init scripts or `systemctl`). Otherwise the paths might be set incorrectly. +[float] +===== docker +[cols="> for Debian/Ubuntu, <> for Redhat/Centos/Fedora, <> for OS X, <> for any Docker platform, and <> for +Windows). + +[NOTE] +================================================== +If you use Apt or Yum, you can <> to update to the newest version more easily. + +See our https://www.elastic.co/downloads/beats/{beatname_lc}[download page] for +other installation options, such as 32-bit images. +================================================== diff --git a/libbeat/docs/shared-template-load.asciidoc b/libbeat/docs/shared-template-load.asciidoc index fafef56808d..bd7c45041b3 100644 --- a/libbeat/docs/shared-template-load.asciidoc +++ b/libbeat/docs/shared-template-load.asciidoc @@ -78,6 +78,13 @@ cd {beatname_lc}-{version}-darwin-x86_64 curl -H 'Content-Type: application/json' -XPUT 'http://localhost:9200/_template/{beatname_lc}' -d@{beatname_lc}.template.json ---------------------------------------------------------------------- +*docker:* + +["source", "sh", subs="attributes"] +---------------------------------------------------------------------- +docker run --rm {dockerimage} curl -H 'Content-Type: application/json' -XPUT 'http://localhost:9200/_template/{beatname_lc}' -d@{beatname_lc}.template.json +---------------------------------------------------------------------- + *win:* endif::allplatforms[] diff --git a/metricbeat/docs/gettingstarted.asciidoc b/metricbeat/docs/gettingstarted.asciidoc index 9adc29ecd62..81336491bf6 100644 --- a/metricbeat/docs/gettingstarted.asciidoc +++ b/metricbeat/docs/gettingstarted.asciidoc @@ -34,19 +34,7 @@ traffic or prevent Metricbeat from collecting metrics when there are network problems. Metrics from multiple Metricbeat instances will be combined on the Elasticsearch server. -To download and install Metricbeat, use the commands that work with your system -(<> for Debian/Ubuntu, <> for Redhat/Centos/Fedora, <> for OS X, and <> for Windows). - -[NOTE] -================================================== -If you use Apt or Yum, you can -<> to -update to the newest version more easily. - -See our https://www.elastic.co/downloads/beats/metricbeat[download page] for -other installation options, such as 32-bit images. -================================================== +include::../../libbeat/docs/shared-download-and-install.asciidoc[] [[deb]] *deb:* @@ -105,6 +93,24 @@ tar xzvf metricbeat-{version}-darwin-x86_64.tar.gz endif::[] +[[docker]] +*docker:* + +ifeval::["{release-state}"=="unreleased"] + +Version {stack-version} of {beatname_uc} has not yet been released. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +["source", "shell", subs="attributes"] +------------------------------------------------ +docker pull {dockerimage} +------------------------------------------------ + +endif::[] + [[win]] *win:* @@ -151,15 +157,7 @@ For more information about these options, see [[metricbeat-configuration]] === Step 2: Configuring Metricbeat -To configure Metricbeat, you edit the configuration file. For rpm and deb, -you'll find the configuration file at `/etc/metricbeat/metricbeat.yml`. For mac -and win, look in the archive that you just extracted. There’s also a full -example configuration file called `metricbeat.full.yml` that shows all -non-deprecated options. - -See the -{libbeat}/config-file-format.html[Config File Format] section of the -_Beats Platform Reference_ for more about the structure of the config file. +include::../../libbeat/docs/shared-configuring.asciidoc[] Metricbeat uses <> to collect metrics. You configure each module individually. The following example shows the default configuration @@ -249,6 +247,7 @@ start Metricbeat in the foreground. ---------------------------------------------------------------------- sudo /etc/init.d/metricbeat start ---------------------------------------------------------------------- + *rpm:* [source,shell] @@ -256,6 +255,13 @@ sudo /etc/init.d/metricbeat start sudo /etc/init.d/metricbeat start ---------------------------------------------------------------------- +*docker:* + +["source", "shell", subs="attributes"] +---------------------------------------------------------------------- +docker run {dockerimage} +---------------------------------------------------------------------- + *mac:* [source,shell] @@ -309,5 +315,3 @@ image:./images/metricbeat_system_dashboard.png[Metricbeat Dashboard] :allplatforms: include::../../libbeat/docs/dashboards.asciidoc[] - - diff --git a/metricbeat/docs/index.asciidoc b/metricbeat/docs/index.asciidoc index cecd6a094a0..3e2d5af4e89 100644 --- a/metricbeat/docs/index.asciidoc +++ b/metricbeat/docs/index.asciidoc @@ -13,6 +13,7 @@ include::../../libbeat/docs/version.asciidoc[] :beatname_uc: Metricbeat :security: X-Pack Security :monitoringdoc: https://www.elastic.co/guide/en/x-pack/current +:dockerimage: docker.elastic.co/beats/{beatname_lc}:{version} include::./overview.asciidoc[] @@ -26,12 +27,12 @@ include::../../libbeat/docs/shared-directory-layout.asciidoc[] include::../../libbeat/docs/repositories.asciidoc[] +include::./running-on-docker.asciidoc[] + include::./upgrading.asciidoc[] include::./how-metricbeat-works.asciidoc[] -include::./metricbeat-in-a-container.asciidoc[] - include::./configuring-howto.asciidoc[] include::./metricbeat-filtering.asciidoc[] diff --git a/metricbeat/docs/metricbeat-in-a-container.asciidoc b/metricbeat/docs/running-on-docker.asciidoc similarity index 69% rename from metricbeat/docs/metricbeat-in-a-container.asciidoc rename to metricbeat/docs/running-on-docker.asciidoc index d15a43b36f4..f9c5c7d50a4 100644 --- a/metricbeat/docs/metricbeat-in-a-container.asciidoc +++ b/metricbeat/docs/running-on-docker.asciidoc @@ -1,45 +1,25 @@ -[[running-in-container]] -== Running Metricbeat in a Container - -ifeval::["{release-state}"=="released"] - -[NOTE] -================================================== -The https://github.com/elastic/beats-docker[official Docker images] for Beats -are available from the Elastic Docker registry. To retrieve the images, simply -issue the `docker pull` command: - -+docker pull docker.elastic.co/beats/metricbeat:{stack-version}+. - -The images are currently under development and should be considered -alpha-quality. We strongly recommend that you do not run these images -in a production environment. - -================================================== - -endif::[] +include::../../libbeat/docs/shared-docker.asciidoc[] +[float] +[[monitoring-host]] +=== Monitoring the Host Machine When executing Metricbeat in a container, there are some important things to be aware of if you want to monitor the host machine or other containers. Let's walk-through some examples using Docker as our container orchestration tool. -[float] -[[monitoring-host]] -=== Monitoring the Host Machine - This example highlights the changes required to make the system module work properly inside of a container. This enables Metricbeat to monitor the host machine from within the container. ["source","sh",subs="attributes"] ---- -sudo docker run \ +docker run \ --volume=/proc:/hostfs/proc:ro \ <1> --volume=/sys/fs/cgroup:/hostfs/sys/fs/cgroup:ro \ <2> --volume=/:/hostfs:ro \ <3> --net=host <4> - docker.elastic.co/beats/metricbeat:{stack-version} -system.hostfs=/hostfs + {dockerimage} -system.hostfs=/hostfs ---- <1> Metricbeat's <> collects much of its data through the Linux proc @@ -49,8 +29,8 @@ container's `/proc` is different than the host's `/proc`. To account for this, y can mount the host's `/proc` filesystem inside of the container and tell Metricbeat to look inside the `/hostfs` directory when looking for `/proc` by using the `-system.hostfs=/hostfs` CLI flag. -<2> If cgroup reporting is enabled for the -<>, then you need +<2> By default, cgroup reporting is enabled for the +<>, so you need to mount the host's cgroup mountpoints within the container. They need to be mounted inside the directory specified by the `-system.hostfs` CLI flag. <3> If you want to be able to monitor filesystems from the host by using the @@ -62,23 +42,28 @@ to make this file contain the host's network devices is to use the `--net=host` flag. This is due to Linux namespacing; simply bind mounting the host's `/proc` to `/hostfs/proc` is not sufficient. +NOTE: The special filesystems +/proc+ and +/sys+ are only available if the +host system is running Linux. Attempts to bind-mount these filesystems will +fail on Windows and MacOS. + [float] [[monitoring-service]] === Monitoring a Service in Another Container -Next let's look at an example of monitoring a containerized service from a +Next, let's look at an example of monitoring a containerized service from a Metricbeat container. ["source","sh",subs="attributes"] ---- -sudo docker run \ - --link some-mysql:mysql \ <1> +docker run \ + --network=mysqlnet \ <1> -e MYSQL_PASSWORD=secret \ <2> - docker.elastic.co/beats/metricbeat:{stack-version}  + {dockerimage} ---- -<1> Linking the containers enables Metricbeat access the exposed ports of the -mysql container, and it makes the hostname `mysql` resolvable to Metricbeat. +<1> Placing the Metricbeat and MySQL containers on the same Docker network +allows Metricbeat access to the exposed ports of the MySQL container, and +makes the hostname `mysql` resolvable to Metricbeat. <2> If you do not want to hardcode certain values into your Metricbeat configuration, then you can pass them into the container either as environment variables or as command line flags to Metricbeat (see the `-E` CLI flag in <>). @@ -95,7 +80,7 @@ metricbeat.modules: password: ${MYSQL_PASSWORD} <2> ---- -<1> The `mysql` hostname will resolve to the `some-mysql` container's address. +<1> The `mysql` hostname will resolve to the address of a container +named `mysql` on the `mysqlnet` Docker network. <2> The `MYSQL_PASSWORD` variable will be evaluated at startup. If the variable is not set, this will lead to an error at startup. - diff --git a/packetbeat/docs/gettingstarted.asciidoc b/packetbeat/docs/gettingstarted.asciidoc index c84c8bbcf4c..d4aab674f84 100644 --- a/packetbeat/docs/gettingstarted.asciidoc +++ b/packetbeat/docs/gettingstarted.asciidoc @@ -25,16 +25,7 @@ After installing the Elastic Stack, read the following topics to learn how to in [[packetbeat-installation]] === Step 1: Installing Packetbeat -To download and install Packetbeat on your application servers, use the commands -that work with your system (<> for Debian/Ubuntu, <> for -Redhat/Centos/Fedora, <> for OS X, and <> for Windows). - -[NOTE] -================================================== -If you use Apt or Yum, you can <> to update to the newest version more easily. - -See our https://www.elastic.co/downloads/beats/packetbeat[download page] for other installation options, such as 32-bit images. -================================================== +include::../../libbeat/docs/shared-download-and-install.asciidoc[] [[deb]] *deb:* @@ -76,6 +67,24 @@ sudo rpm -vi packetbeat-{version}-x86_64.rpm endif::[] +[[docker]] +*docker:* + +ifeval::["{release-state}"=="unreleased"] + +Version {stack-version} of {beatname_uc} has not yet been released. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +["source", "shell", subs="attributes"] +------------------------------------------------ +docker pull {dockerimage} +------------------------------------------------ + +endif::[] + [[mac]] *mac:* @@ -138,14 +147,7 @@ more information about these options, see <>. [[configuring-packetbeat]] === Step 2: Configuring Packetbeat -To configure Packetbeat, you edit the configuration file. For rpm and deb, you'll -find the configuration file at `/etc/packetbeat/packetbeat.yml`. For mac and win, look in -the archive that you just extracted. There’s also a full example configuration file called -`packetbeat.full.yml` that shows all non-deprecated options. - -See the -{libbeat}/config-file-format.html[Config File Format] section of the -_Beats Platform Reference_ for more about the structure of the config file. +include::../../libbeat/docs/shared-configuring.asciidoc[] To configure Packetbeat: @@ -274,6 +276,13 @@ sudo /etc/init.d/packetbeat start sudo /etc/init.d/packetbeat start ---------------------------------------------------------------------- +*docker:* + +["source", "shell", subs="attributes"] +---------------------------------------------------------------------- +docker run {dockerimage} +---------------------------------------------------------------------- + *mac:* [source,shell] @@ -329,5 +338,3 @@ image:./images/packetbeat-statistics.png[Packetbeat statistics] :allplatforms: include::../../libbeat/docs/dashboards.asciidoc[] - - diff --git a/packetbeat/docs/index.asciidoc b/packetbeat/docs/index.asciidoc index 745b385fb49..d82845ba0f0 100644 --- a/packetbeat/docs/index.asciidoc +++ b/packetbeat/docs/index.asciidoc @@ -17,6 +17,7 @@ include::../../libbeat/docs/version.asciidoc[] :beatname_lc: packetbeat :beatname_uc: Packetbeat :security: X-Pack Security +:dockerimage: docker.elastic.co/beats/{beatname_lc}:{version} include::./overview.asciidoc[] @@ -30,6 +31,8 @@ include::../../libbeat/docs/shared-directory-layout.asciidoc[] include::../../libbeat/docs/repositories.asciidoc[] +include::./running-on-docker.asciidoc[] + include::./upgrading.asciidoc[] include::./configuring-howto.asciidoc[] diff --git a/packetbeat/docs/running-on-docker.asciidoc b/packetbeat/docs/running-on-docker.asciidoc new file mode 100644 index 00000000000..fd939cc46f4 --- /dev/null +++ b/packetbeat/docs/running-on-docker.asciidoc @@ -0,0 +1,29 @@ +include::../../libbeat/docs/shared-docker.asciidoc[] + +=== Required Network Capabilities + +Under Docker, Packetbeat runs as a non-root user, but requires some privileged +network capabilities to operate correctly. Ensure that the +NET_ADMIN+ +capability is available to the container. + +["source","sh",subs="attributes"] +---- +docker run --cap-add=NET_ADMIN {dockerimage} +---- + +=== Capturing Traffic from the Host System + +By default, Docker networking will connect the Packetbeat container to an +isolated virtual network, with a limited view of network traffic. You may wish +to connect the container directly to the host network in order to see traffic +destined for, and originating from, the host system. With +docker run+, this can +be achieved by specifying +--network=host+. + +["source","sh",subs="attributes"] +---- +docker run --cap-add=NET_ADMIN --network=host {dockerimage} +---- + +NOTE: On Windows and MacOS, specifying +--network=host+ will bind the +container's network interface to the virtual interface of Docker's embedded +Linux virtual machine, not to the physical interface of the host system.