[docs] Restructure module docs (elastic#16571)

dedemorton · Feb 29, 2020 · e36a5d9 · e36a5d9
1 parent c1c4943
commit e36a5d9
Show file tree

Hide file tree

Showing 75 changed files with 676 additions and 652 deletions.
diff --git a/filebeat/docs/include/gs-link.asciidoc b/filebeat/docs/include/gs-link.asciidoc
@@ -0,0 +1,2 @@
+TIP: Read the <<filebeat-modules-quickstart,quick start>> to learn how to set up and
+run modules.
diff --git a/filebeat/docs/modules/activemq.asciidoc b/filebeat/docs/modules/activemq.asciidoc
@@ -16,13 +16,13 @@ This module parses Apache ActiveMQ logs. It supports application and audit logs.
 
 include::../include/what-happens.asciidoc[]
 
+include::../include/gs-link.asciidoc[]
+
 [float]
 === Compatibility
 
 The module has been tested with ActiveMQ 5.13.0 and 5.15.9. Other versions are expected to work.
 
-include::../include/running-modules.asciidoc[]
-
 include::../include/configuring-intro.asciidoc[]
 
 :fileset_ex: log

diff --git a/filebeat/docs/modules/apache.asciidoc b/filebeat/docs/modules/apache.asciidoc
@@ -13,6 +13,8 @@ https://httpd.apache.org/[Apache HTTP] server.
 
 include::../include/what-happens.asciidoc[]
 
+include::../include/gs-link.asciidoc[]
+
 [float]
 === Compatibility
 
@@ -21,16 +23,6 @@ The +{modulename}+ module was tested with logs from versions 2.2.22 and 2.4.23.
 On Windows, the module was tested with Apache HTTP Server installed from the Chocolatey
 repository.
 
-include::../include/running-modules.asciidoc[]
-
-[float]
-=== Example dashboard
-
-This module comes with a sample dashboard. For example:
-
-[role="screenshot"]
-image::./images/kibana-apache.png[]
-
 include::../include/configuring-intro.asciidoc[]
 
 The following example shows how to set paths in the +modules.d/{modulename}.yml+
@@ -86,6 +78,14 @@ Add %v config in httpd.conf in log section
     LogFormat "%v %h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
 -----
 
+[float]
+=== Example dashboard
+
+This module comes with a sample dashboard. For example:
+
+[role="screenshot"]
+image::./images/kibana-apache.png[]
+
 :has-dashboards!:
 
 :fileset_ex!:

diff --git a/filebeat/docs/modules/auditd.asciidoc b/filebeat/docs/modules/auditd.asciidoc
@@ -13,6 +13,8 @@ The +{modulename}+ module collects and parses logs from the audit daemon
 
 include::../include/what-happens.asciidoc[]
 
+include::../include/gs-link.asciidoc[]
+
 [float]
 === Compatibility
 
@@ -21,18 +23,6 @@ The +{modulename}+ module was tested with logs from `auditd` on OSes like CentOS
 
 This module is not available for Windows.
 
-include::../include/running-modules.asciidoc[]
-
-[float]
-=== Example dashboard
-
-This module comes with a sample dashboard showing an overview of the audit log
-data. You can build more specific dashboards that are tailored to the audit
-rules that you use on your systems.
-
-[role="screenshot"]
-image::./images/kibana-audit-auditd.png[]
-
 include::../include/configuring-intro.asciidoc[]
 
 The following example shows how to set paths in the +modules.d/{modulename}.yml+
@@ -67,6 +57,16 @@ include::../include/config-option-intro.asciidoc[]
 
 include::../include/var-paths.asciidoc[]
 
+[float]
+=== Example dashboard
+
+This module comes with a sample dashboard showing an overview of the audit log
+data. You can build more specific dashboards that are tailored to the audit
+rules that you use on your systems.
+
+[role="screenshot"]
+image::./images/kibana-audit-auditd.png[]
+
 :has-dashboards!:
 
 :fileset_ex!:

diff --git a/filebeat/docs/modules/aws.asciidoc b/filebeat/docs/modules/aws.asciidoc
@@ -23,6 +23,8 @@ from network interfaces in AWS VPC. ELB access logs captures detailed informatio
 about requests sent to the load balancer. CloudTrail logs contain events
 that represent actions taken by a user, role or AWS service.
 
+include::../include/gs-link.asciidoc[]
+
 [float]
 === Module configuration
 

diff --git a/filebeat/docs/modules/azure.asciidoc b/filebeat/docs/modules/azure.asciidoc
@@ -8,20 +8,18 @@ This file is generated! See scripts/docs_collector.py
 :modulename: azure
 :has-dashboards: false
 
-== azure module
+== Azure module
 
 beta[]
 
-This is the azure module.
-
-The azure module will concentrate on retrieving different types of log data from Azure.
+The azure module retrieves different types of log data from Azure.
 There are several requirements before using the module since the logs will actually be read from azure event hubs.
 
    - the logs have to be exported first to the event hubs https://docs.microsoft.com/en-us/azure/event-hubs/event-hubs-create-kafka-enabled
    - to export activity logs to event hubs users can follow the steps here https://docs.microsoft.com/en-us/azure/azure-monitor/platform/activity-log-export
    - to export audit and sign-in logs to event hubs users can follow the steps here https://docs.microsoft.com/en-us/azure/active-directory/reports-monitoring/tutorial-azure-monitor-stream-logs-to-event-hub
 
-The module will contain the following filesets:
+The module contains the following filesets:
 
 `activitylogs` ::
 Will retrieve azure activity logs. Control-plane events on Azure Resource Manager resources. Activity logs provide insight into the operations that were performed on resources in your subscription.
@@ -32,14 +30,6 @@ Will retrieve azure Active Directory sign-in logs. The sign-ins report provides
 `auditlogs` ::
 Will retrieve azure Active Directory audit logs. The audit logs provide traceability through logs for all changes done by various features within Azure AD. Examples of audit logs include changes made to any resources within Azure AD like adding or removing users, apps, groups, roles and policies.
 
-[float]
-=== Dashboards
-
-The azure module comes with several predefined dashboards for general cloud overview, user activity and alerts. For example:
-
-image::./images/filebeat-azure-overview.png[]
-
-
 [float]
 === Module configuration
 
@@ -100,14 +90,22 @@ The name of the storage account the state/offsets will be stored and updated.
 _string_
 The storage account key, this key will be used to authorize access to data in your storage account.
 
-
 include::../include/what-happens.asciidoc[]
 
+include::../include/gs-link.asciidoc[]
+
 [float]
 === Compatibility
 
 TODO: document with what versions of the software is this tested
 
+[float]
+=== Dashboards
+
+The azure module comes with several predefined dashboards for general cloud overview, user activity and alerts. For example:
+
+image::./images/filebeat-azure-overview.png[]
+
 
 
 

diff --git a/filebeat/docs/modules/cef.asciidoc b/filebeat/docs/modules/cef.asciidoc
@@ -18,7 +18,7 @@ encoded data. The decoded data is written into a `cef` object field. Lastly any
 Elastic Common Schema (ECS) fields that can be populated with the CEF data are
 populated.
 
-include::../include/running-modules.asciidoc[]
+include::../include/gs-link.asciidoc[]
 
 include::../include/configuring-intro.asciidoc[]
 

diff --git a/filebeat/docs/modules/cisco.asciidoc b/filebeat/docs/modules/cisco.asciidoc
@@ -36,15 +36,7 @@ Check the <<dynamic-script-compilations>> section for more information.
 
 include::../include/what-happens.asciidoc[]
 
-include::../include/running-modules.asciidoc[]
-
-[float]
-=== Example dashboard
-
-This module comes with a sample dashboard for ASA:
-
-[role="screenshot"]
-image::./images/kibana-cisco-asa.png[]
+include::../include/gs-link.asciidoc[]
 
 include::../include/configuring-intro.asciidoc[]
 
@@ -307,6 +299,14 @@ parameters on your Elasticsearch cluster:
 - {ref}/modules-scripting-using.html#modules-scripting-using-caching[script.cache_max_size]:
   Increase to at least `200` if using both filesets or other script-heavy modules.
 
+[float]
+=== Example dashboard
+
+This module comes with a sample dashboard for ASA:
+
+[role="screenshot"]
+image::./images/kibana-cisco-asa.png[]
+
 :modulename!:
 
 

diff --git a/filebeat/docs/modules/coredns.asciidoc b/filebeat/docs/modules/coredns.asciidoc
@@ -13,19 +13,19 @@ This file is generated! See scripts/docs_collector.py
 This is a filebeat module for CoreDNS. It supports both standalone CoreDNS deployment and
 CoreDNS deployment in Kubernetes.
 
+include::../include/gs-link.asciidoc[]
+
 [float]
 === Compatibility
 
 Although this module has been developed against Kubernetes v1.13.x, it is expected to work
 with other versions of Kubernetes.
 
-[float]
-=== Example dashboard
+include::../include/configuring-intro.asciidoc[]
 
-This module comes with a sample dashboard.
+:fileset_ex: log
 
-[role="screenshot"]
-image::./images/kibana-coredns.jpg[]
+include::../include/config-option-intro.asciidoc[]
 
 [float]
 ==== `log` fileset settings
@@ -47,6 +47,14 @@ include::../include/var-paths.asciidoc[]
 
 An array of tags describing the monitored CoreDNS setup.
 
+[float]
+=== Example dashboard
+
+This module comes with a sample dashboard.
+
+[role="screenshot"]
+image::./images/kibana-coredns.jpg[]
+
 
 [float]
 === Fields

diff --git a/filebeat/docs/modules/elasticsearch.asciidoc b/filebeat/docs/modules/elasticsearch.asciidoc
@@ -14,15 +14,13 @@ This is the elasticsearch module.
 
 include::../include/what-happens.asciidoc[]
 
+include::../include/gs-link.asciidoc[]
+
 [float]
 === Compatibility
 
 The Elasticsearch module is compatible with Elasticsearch 6.2 and newer.
 
-
-include::../include/running-modules.asciidoc[]
-
-
 include::../include/configuring-intro.asciidoc[]
 
 :fileset_ex: server

diff --git a/filebeat/docs/modules/envoyproxy.asciidoc b/filebeat/docs/modules/envoyproxy.asciidoc
@@ -10,7 +10,9 @@ This file is generated! See scripts/docs_collector.py
 
 == Envoyproxy Module
 
-This is a filebeat module for Envoy proxy access log (https://www.envoyproxy.io/docs/envoy/v1.10.0/configuration/access_log). It supports both standalone deployment and Envoy proxy deployment in Kubernetes. 
+This is a Filebeat module for Envoy proxy access log (https://www.envoyproxy.io/docs/envoy/v1.10.0/configuration/access_log). It supports both standalone deployment and Envoy proxy deployment in Kubernetes. 
+
+include::../include/gs-link.asciidoc[]
 
 [float]
 === Compatibility

diff --git a/filebeat/docs/modules/googlecloud.asciidoc b/filebeat/docs/modules/googlecloud.asciidoc
@@ -18,7 +18,7 @@ Google Pub/Sub topic sink.
 
 include::../include/what-happens.asciidoc[]
 
-include::../include/running-modules.asciidoc[]
+include::../include/gs-link.asciidoc[]
 
 include::../include/configuring-intro.asciidoc[]
 

diff --git a/filebeat/docs/modules/haproxy.asciidoc b/filebeat/docs/modules/haproxy.asciidoc
@@ -12,24 +12,15 @@ The +{modulename}+ module collects and parses logs from a (`haproxy`) process.
 
 include::../include/what-happens.asciidoc[]
 
+include::../include/gs-link.asciidoc[]
+
 [float]
 === Compatibility
 
 The +{modulename}+ module was tested with logs from `haproxy` running on AWS Linux as a gateway to a cluster of microservices.
 
 This module is not available for Windows.
 
-include::../include/running-modules.asciidoc[]
-
-[float]
-=== Example dashboard
-
-This module comes with a sample dashboard showing geolocation, distribution of requests between backends and frontends,
-and status codes over time. For example:
-
-[role="screenshot"]
-image::./images/kibana-haproxy-overview.png[]
-
 include::../include/configuring-intro.asciidoc[]
 
 The module is by default configured to run via syslog on port 9001. However
@@ -56,6 +47,15 @@ include::../include/var-paths.asciidoc[]
 
 include::../include/timezone-support.asciidoc[]
 
+[float]
+=== Example dashboard
+
+This module comes with a sample dashboard showing geolocation, distribution of requests between backends and frontends,
+and status codes over time. For example:
+
+[role="screenshot"]
+image::./images/kibana-haproxy-overview.png[]
+
 :has-dashboards!:
 
 :fileset_ex!:

diff --git a/filebeat/docs/modules/ibmmq.asciidoc b/filebeat/docs/modules/ibmmq.asciidoc
@@ -13,25 +13,15 @@ The `ibmmq` module collects and parses the queue manager error logs from IBM MQ
 
 include::../include/what-happens.asciidoc[]
 
+include::../include/gs-link.asciidoc[]
+
 [float]
 === Compatibility
 
 This module has been tested with IBM MQ v9.1.0.0, but it should be compatible with older versions.
 
-include::../include/running-modules.asciidoc[]
-
-[float]
-=== Example dashboard
-
-This module comes with a sample dashboard. For example:
-
-[role="screenshot"]
-image::./images/filebeat-ibmmq.png[]
-
-
 include::../include/configuring-intro.asciidoc[]
 
-
 The following example shows how to set paths in the +modules.d/{modulename}.yml+
 file to override the default paths for IBM MQ errorlog:
 
@@ -42,6 +32,7 @@ file to override the default paths for IBM MQ errorlog:
     enabled: true
     var.paths: ["C:/ibmmq/logs/*.log"]
 -----
+
 :fileset_ex: errorlog
 
 include::../include/config-option-intro.asciidoc[]
@@ -51,6 +42,14 @@ include::../include/config-option-intro.asciidoc[]
 
 include::../include/var-paths.asciidoc[]
 
+[float]
+=== Example dashboard
+
+This module comes with a sample dashboard. For example:
+
+[role="screenshot"]
+image::./images/filebeat-ibmmq.png[]
+
 :fileset_ex!:
 
 :modulename!: