diff --git a/auditbeat/docs/configuring-howto.asciidoc b/auditbeat/docs/configuring-howto.asciidoc index c4ab3ee230b..f52e7abb0d6 100644 --- a/auditbeat/docs/configuring-howto.asciidoc +++ b/auditbeat/docs/configuring-howto.asciidoc @@ -7,21 +7,7 @@ Configure ++++ -Before modifying configuration settings, make sure you've completed the -<<{beatname_lc}-configuration,configuration steps>> in the Getting Started. -This section describes some common use cases for changing configuration options. - -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+. -There's also a full example configuration file at -+/etc/{beatname_lc}/{beatname_lc}.reference.yml+ that shows all non-deprecated -options. For mac and win, look in the archive that you extracted. - -The {beatname_uc} configuration file uses http://yaml.org/[YAML] for its syntax. -See the {beats-ref}/config-file-format.html[Config File Format] section of the -_Beats Platform Reference_ for more about the structure of the config file. - -The following topics describe how to configure {beatname_uc}: +include::{libbeat-dir}/shared/configuring-intro.asciidoc[] * <> * <> diff --git a/auditbeat/docs/getting-started.asciidoc b/auditbeat/docs/getting-started.asciidoc index f5bd61f1aba..5f4908640ad 100644 --- a/auditbeat/docs/getting-started.asciidoc +++ b/auditbeat/docs/getting-started.asciidoc @@ -1,182 +1,70 @@ -[id="{beatname_lc}-getting-started"] -== Get started with {beatname_uc} +[id="{beatname_lc}-installation-configuration"] +== {beatname_uc} quick start: installation and configuration ++++ -Get started +Quick start: installation and configuration ++++ -include::{libbeat-dir}/shared-getting-started-intro.asciidoc[] +This guide describes how to get started quickly with audit data collection. +You'll learn how to: -* <<{beatname_lc}-installation>> -* <<{beatname_lc}-configuration>> -* <<{beatname_lc}-template>> -* <> -* <<{beatname_lc}-starting>> -* <> -* <> +* install {beatname_uc} on each system you want to monitor +* specify the location of your audit data +* parse log data into fields and send it to {es} +* visualize the log data in {kib} -[id="{beatname_lc}-installation"] -=== Step 1: Install {beatname_uc} - -Install {beatname_uc} on all the servers you want to monitor. - -include::{libbeat-dir}/shared-download-and-install.asciidoc[] - -[[deb]] -*deb:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes"] ------------------------------------------------- -curl -L -O https://artifacts.elastic.co/downloads/beats/{beatname_lc}/{beatname_lc}-{version}-amd64.deb -sudo dpkg -i {beatname_lc}-{version}-amd64.deb ------------------------------------------------- - -endif::[] - -[[rpm]] -*rpm:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes"] ------------------------------------------------- -curl -L -O https://artifacts.elastic.co/downloads/beats/{beatname_lc}/{beatname_lc}-{version}-x86_64.rpm -sudo rpm -vi {beatname_lc}-{version}-x86_64.rpm ------------------------------------------------- - -endif::[] - -[[mac]] -*mac:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes"] ------------------------------------------------- -curl -L -O https://artifacts.elastic.co/downloads/beats/{beatname_lc}/{beatname_lc}-{version}-darwin-x86_64.tar.gz -tar xzvf {beatname_lc}-{version}-darwin-x86_64.tar.gz ------------------------------------------------- - -endif::[] - -include::{libbeat-dir}/shared-brew-install.asciidoc[] - -[[linux]] -*linux:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes"] ------------------------------------------------- -curl -L -O https://artifacts.elastic.co/downloads/beats/{beatname_lc}/{beatname_lc}-{version}-linux-x86_64.tar.gz -tar xzvf {beatname_lc}-{version}-linux-x86_64.tar.gz ------------------------------------------------- - -endif::[] - -[[docker]] -*docker:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes"] ------------------------------------------------- -curl -L -O https://artifacts.elastic.co/downloads/beats/{beatname_lc}/{beatname_lc}-{version}-linux-x86_64.tar.gz -tar xzvf {beatname_lc}-{version}-linux-x86_64.tar.gz ------------------------------------------------- - -endif::[] - -See <> for deploying Docker containers. - -[[win]] -*win:* +[role="screenshot"] +image::./images/auditbeat-auditd-dashboard.png[{beatname_uc} Auditd dashboard] -ifeval::["{release-state}"=="unreleased"] +[float] +=== Before you begin -Version {version} of {beatname_uc} has not yet been released. +You need {es} for storing and searching your data, and {kib} for visualizing and +managing it. -endif::[] +include::{libbeat-dir}/tab-widgets/spinup-stack-widget.asciidoc[] -ifeval::["{release-state}"!="unreleased"] +[float] +[[install]] +=== Step 1: Install {beatname_uc} -. Download the {beatname_uc} Windows zip file from the -https://www.elastic.co/downloads/beats/{beatname_lc}[downloads page]. +Install {beatname_uc} on all the servers you want to monitor. -. Extract the contents of the zip file into `C:\Program Files`. +To download and install {beatname_uc}, use the commands that work with your +system: -. Rename the +{beatname_lc}--windows+ directory to +{beatname_uc}+. +include::{libbeat-dir}/tab-widgets/install-widget.asciidoc[] -. Open a PowerShell prompt as an Administrator (right-click the PowerShell icon -and select *Run As Administrator*). +[float] +[[other-installation-options]] +==== Other installation options -. From the PowerShell prompt, run the following commands to install {beatname_uc} -as a Windows service: -+ -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -PS > cd 'C:{backslash}Program Files{backslash}{beatname_uc}' -PS C:{backslash}Program Files{backslash}{beatname_uc}> .{backslash}install-service-{beatname_lc}.ps1 ----------------------------------------------------------------------- +* <> +* https://www.elastic.co/downloads/beats/{beatname_lc}[Download page] +* <> +* <> -NOTE: If script execution is disabled on your system, you need to set the -execution policy for the current session to allow the script to run. For -example: +PowerShell.exe -ExecutionPolicy UnRestricted -File -.\install-service-{beatname_lc}.ps1+. +[float] +[[set-connection]] +=== Step 2: Connect to the {stack} -endif::[] +include::{libbeat-dir}/shared/connecting-to-es.asciidoc[] -Before starting {beatname_uc}, you should look at the configuration options in the -configuration file, for example +C:{backslash}Program Files{backslash}{beatname_uc}{backslash}{beatname_lc}.yml+. -For more information about these options, see -<>. +[float] +[[enable-modules]] +=== Step 3: Configure data collection modules -[id="{beatname_lc}-configuration"] -=== Step 2: Configure {beatname_uc} +{beatname_uc} uses <> to collect audit information. -include::{libbeat-dir}/shared-configuring.asciidoc[] +By default, {beatname_uc} uses a configuration that's tailored to the operating +system where {beatname_uc} is running. -To configure {beatname_uc}: +To use a different configuration, change the module settings in ++{beatname_lc}.yml+. -. Define the {beatname_uc} modules that you want to enable. {beatname_uc} uses -modules to collect the audit information. For each module, specify the -metricsets that you want to collect. -+ The following example shows the `file_integrity` module configured to generate events whenever a file in one of the specified paths changes on disk: -+ + ["source","sh",subs="attributes"] ------------------------------------- auditbeat.modules: @@ -189,105 +77,74 @@ auditbeat.modules: - /usr/sbin - /etc ------------------------------------- -+ -If you accept the default configuration without specifying additional modules, -{beatname_uc} uses a configuration that's tailored to the operating system where -{beatname_uc} is running. -+ -See <> for more details about configuring modules. -include::{libbeat-dir}/step-configure-output.asciidoc[] -include::{libbeat-dir}/step-configure-kibana-endpoint.asciidoc[] +include::{libbeat-dir}/shared/config-check.asciidoc[] -include::{libbeat-dir}/step-configure-credentials.asciidoc[] +[float] +[[setup-assets]] +=== Step 4: Set up assets -include::{libbeat-dir}/step-test-config.asciidoc[] +{beatname_uc} comes with predefined assets for parsing, indexing, and +visualizing your data. To load these assets: -include::{libbeat-dir}/step-look-at-config.asciidoc[] +. Make sure the user specified in +{beatname_lc}.yml+ is +<>. -[id="{beatname_lc}-template"] -=== Step 3: Load the index template in {es} - -include::{libbeat-dir}/shared-template-load.asciidoc[] +. From the installation directory, run: ++ +-- +include::{libbeat-dir}/tab-widgets/setup-widget.asciidoc[] +-- ++ +`-e` is optional and sends output to standard error instead of the configured log output. -[[load-kibana-dashboards]] -=== Step 4: Set up the {kib} dashboards +This step loads the recommended {ref}/indices-templates.html[index template] for writing to {es} +and deploys the sample dashboards for visualizing the data in {kib}. -include::{libbeat-dir}/dashboards.asciidoc[] +[TIP] +===== +A connection to {es} (or {ess}) is required to set up the initial +environment. If you're using a different output, such as {ls}, see +<> and <>. +===== -[id="{beatname_lc}-starting"] +[float] +[[start]] === Step 5: Start {beatname_uc} -Run {beatname_uc} by issuing the appropriate command for your platform. If you -are accessing a secured {es} cluster, make sure you've configured credentials as -described in <<{beatname_lc}-configuration>>. - -NOTE: If you use an init.d script to start {beatname_uc} on deb or rpm, you can't -specify command line flags (see <>). To specify flags, -start {beatname_uc} in the foreground. - -*deb and rpm:* +Before starting {beatname_uc}, modify the user credentials in ++{beatname_lc}.yml+ and specify a user who is +<>. -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -sudo service {beatname_lc} start ----------------------------------------------------------------------- +To start {beatname_uc}, run: -*mac and linux:* +// tag::start-step[] +include::{libbeat-dir}/tab-widgets/start-widget.asciidoc[] +// end::start-step[] -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -sudo chown root {beatname_lc}.yml <1> -sudo ./{beatname_lc} -e ----------------------------------------------------------------------- -<1> To monitor system files, you'll be running {beatname_uc} as root, so you -need to change ownership of the configuration file, or run {beatname_uc} with -`--strict.perms=false` specified. See -{beats-ref}/config-file-permissions.html[Config File Ownership and Permissions] -in the _Beats Platform Reference_. +{beatname_uc} should begin streaming events to {es}. If you see a warning about too many open files, you need to increase the `ulimit`. See the <> for more details. -include::{libbeat-dir}/shared-brew-run.asciidoc[] - -*win:* - -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -PS C:{backslash}Program Files{backslash}{beatname_uc}> Start-Service {beatname_lc} ----------------------------------------------------------------------- +[float] +[[view-data]] +=== Step 6: View your data in {kib} -By default the log files are stored in +C:{backslash}ProgramData{backslash}{beatname_lc}{backslash}Logs+. - -==== Test the {beatname_uc} installation - -To verify that your server's statistics are present in {es}, issue the following -command: - -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -curl -XGET 'http://localhost:9200/{beatname_lc}-*/_search?pretty' ----------------------------------------------------------------------- - -Make sure that you replace `localhost:9200` with the address of your {es} -instance. - -On Windows, if you don't have cURL installed, simply point your browser to the -URL. +To make it easier for you to start auditing the activities of users and +processes on your system, {beatname_uc} comes with pre-built {kib} dashboards +and UIs for visualizing your data. -[[view-kibana-dashboards]] -=== Step 6: View the sample {kib} dashboards +include::{libbeat-dir}/shared/opendashboards.asciidoc[tag=open-dashboards] -To make it easier for you to start auditing the activities of users and -processes on your system, we have created example {beatname_uc} dashboards. -You loaded the dashboards earlier when you ran the `setup` command. +[float] +=== What's next? -include::{libbeat-dir}/opendashboards.asciidoc[] +Now that you have audit data streaming into {es}, learn how to unify your logs, +metrics, uptime, and application performance data. -The dashboards are provided as examples. We recommend that you -{kibana-ref}/dashboard.html[customize] them to meet your needs. +include::{libbeat-dir}/shared/obs-apps.asciidoc[] -[role="screenshot"] -image::./images/auditbeat-file-integrity-dashboard.png[Auditbeat File Integrity Dashboard] +// Add Javascript and CSS for tabbed panels +include::{libbeat-dir}/tab-widgets/code.asciidoc[] diff --git a/auditbeat/docs/howto/howto.asciidoc b/auditbeat/docs/howto/howto.asciidoc index 54eef117163..0c0334f2902 100644 --- a/auditbeat/docs/howto/howto.asciidoc +++ b/auditbeat/docs/howto/howto.asciidoc @@ -5,22 +5,32 @@ -- Learn how to perform common {beatname_uc} configuration tasks. +* <<{beatname_lc}-template>> +* <> +* <> * <<{beatname_lc}-geoip>> * <> * <> +* <> * <> -- +include::{libbeat-dir}/howto/load-index-templates.asciidoc[] + +include::{libbeat-dir}/howto/change-index-name.asciidoc[] + +include::{libbeat-dir}/howto/load-dashboards.asciidoc[] + include::{libbeat-dir}/shared-geoip.asciidoc[] +include::{libbeat-dir}/shared-config-ingest.asciidoc[] + :standalone: include::{libbeat-dir}/shared-env-vars.asciidoc[] :standalone!: -include::{libbeat-dir}/shared-config-ingest.asciidoc[] - :standalone: include::{libbeat-dir}/yaml.asciidoc[] :standalone!: diff --git a/auditbeat/docs/images/auditbeat-auditd-dashboard.png b/auditbeat/docs/images/auditbeat-auditd-dashboard.png new file mode 100644 index 00000000000..34d1deb61db Binary files /dev/null and b/auditbeat/docs/images/auditbeat-auditd-dashboard.png differ diff --git a/auditbeat/docs/images/auditbeat-file-integrity-dashboard.png b/auditbeat/docs/images/auditbeat-file-integrity-dashboard.png deleted file mode 100644 index 866888a17cf..00000000000 Binary files a/auditbeat/docs/images/auditbeat-file-integrity-dashboard.png and /dev/null differ diff --git a/auditbeat/docs/images/kibana-created-indexes.png b/auditbeat/docs/images/kibana-created-indexes.png deleted file mode 100644 index af8ad91a502..00000000000 Binary files a/auditbeat/docs/images/kibana-created-indexes.png and /dev/null differ diff --git a/auditbeat/docs/images/kibana-navigation-vis.png b/auditbeat/docs/images/kibana-navigation-vis.png deleted file mode 100644 index d3494763959..00000000000 Binary files a/auditbeat/docs/images/kibana-navigation-vis.png and /dev/null differ diff --git a/auditbeat/docs/index.asciidoc b/auditbeat/docs/index.asciidoc index 43f68815848..b236e1a6eee 100644 --- a/auditbeat/docs/index.asciidoc +++ b/auditbeat/docs/index.asciidoc @@ -31,8 +31,6 @@ include::./overview.asciidoc[] include::./getting-started.asciidoc[] -include::{libbeat-dir}/repositories.asciidoc[] - include::./setting-up-running.asciidoc[] include::./upgrading.asciidoc[] @@ -55,3 +53,4 @@ include::./faq.asciidoc[] include::{libbeat-dir}/contributing-to-beats.asciidoc[] +include::{libbeat-dir}/shared/redirects.asciidoc[] diff --git a/auditbeat/docs/overview.asciidoc b/auditbeat/docs/overview.asciidoc index 951b9059583..547638ff509 100644 --- a/auditbeat/docs/overview.asciidoc +++ b/auditbeat/docs/overview.asciidoc @@ -1,10 +1,6 @@ [id="{beatname_lc}-overview"] == {beatname_uc} overview -++++ -Overview -++++ - {beatname_uc} is a lightweight shipper that you can install on your servers to audit the activities of users and processes on your systems. For example, you can use {beatname_uc} to collect and centralize audit events from the Linux diff --git a/auditbeat/docs/setting-up-running.asciidoc b/auditbeat/docs/setting-up-running.asciidoc index 61f952b94c3..4e2bd8265f9 100644 --- a/auditbeat/docs/setting-up-running.asciidoc +++ b/auditbeat/docs/setting-up-running.asciidoc @@ -11,23 +11,31 @@ Set up and run ++++ -Before reading this section, see the -<<{beatname_lc}-getting-started,getting started documentation>> for basic +Before reading this section, see +<<{beatname_lc}-installation-configuration>> for basic installation instructions to get you started. -This section includes additional information on how to set up and run +This section includes additional information on how to install, set up, and run {beatname_uc}, including: * <> +* <> + * <> +* <> + * <> * <> * <> +* <<{beatname_lc}-starting>> + +* <> + //MAINTAINERS: If you add a new file to this section, make sure you update the bulleted list ^^ too. @@ -37,10 +45,14 @@ include::{libbeat-dir}/keystore.asciidoc[] include::{libbeat-dir}/command-reference.asciidoc[] +include::{libbeat-dir}/repositories.asciidoc[] + include::./running-on-docker.asciidoc[] include::./running-on-kubernetes.asciidoc[] include::{libbeat-dir}/shared-systemd.asciidoc[] -include::{libbeat-dir}/shared-shutdown.asciidoc[] +include::{libbeat-dir}/shared/start-beat.asciidoc[] + +include::{libbeat-dir}/shared/shutdown.asciidoc[] diff --git a/auditbeat/docs/upgrading.asciidoc b/auditbeat/docs/upgrading.asciidoc index a897301c642..132cb1db843 100644 --- a/auditbeat/docs/upgrading.asciidoc +++ b/auditbeat/docs/upgrading.asciidoc @@ -1,7 +1,7 @@ [[upgrading-auditbeat]] == Upgrade Auditbeat -For information about upgrading to a new version, see the following topics in the _Beats Platform Reference_: +For information about upgrading to a new version, see: * {beats-ref}/breaking-changes.html[Breaking Changes] * {beats-ref}/upgrading.html[Upgrade] diff --git a/dev-tools/packaging/templates/common/README.md.tmpl b/dev-tools/packaging/templates/common/README.md.tmpl index 5754ce7f87f..01491d39148 100644 --- a/dev-tools/packaging/templates/common/README.md.tmpl +++ b/dev-tools/packaging/templates/common/README.md.tmpl @@ -15,7 +15,7 @@ instance. To load the dashboards for {{.BeatName | title}} into Kibana, run: ./{{.BeatName}} setup -e For further steps visit the -[Getting started](https://www.elastic.co/guide/en/beats/{{.BeatName}}/{{ beat_doc_branch }}/{{.BeatName}}-getting-started.html) guide. +[Quick start](https://www.elastic.co/guide/en/beats/{{.BeatName}}/{{ beat_doc_branch }}/{{.BeatName}}-installation-configuration.html) guide. ## Documentation diff --git a/dev-tools/packaging/templates/darwin/README.html.tmpl b/dev-tools/packaging/templates/darwin/README.html.tmpl index 9c2b8687bfe..5ba3970f55c 100644 --- a/dev-tools/packaging/templates/darwin/README.html.tmpl +++ b/dev-tools/packaging/templates/darwin/README.html.tmpl @@ -22,7 +22,7 @@ instance. To load the dashboards for {{.BeatName | title}} into Kibana, run:

For further steps visit the -Getting started guide.

+Quick start guide.

Documentation

diff --git a/filebeat/README.md b/filebeat/README.md index 6bbe0057ba1..b47e54f4138 100644 --- a/filebeat/README.md +++ b/filebeat/README.md @@ -6,9 +6,9 @@ Together with the libbeat lumberjack output is a replacement for [logstash-forwa To learn more about Filebeat, check out https://www.elastic.co/products/beats/filebeat. -## Getting started +## Quick start -Please follow the [getting started](https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-getting-started.html) +Please follow the [quick start](https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-installation-configuration.html) guide from the docs. ## Documentation diff --git a/filebeat/docs/configuring-howto.asciidoc b/filebeat/docs/configuring-howto.asciidoc index ab72b70d043..89a8f4b4f2d 100644 --- a/filebeat/docs/configuring-howto.asciidoc +++ b/filebeat/docs/configuring-howto.asciidoc @@ -7,23 +7,10 @@ Configure ++++ -Before modifying configuration settings, make sure you've completed the -<> in the Getting Started. -This section describes some common use cases for changing configuration options. - -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+. -There's also a full example configuration file at -+/etc/{beatname_lc}/{beatname_lc}.reference.yml+ that shows all non-deprecated -options. For mac and win, look in the archive that you extracted. - -The {beatname_uc} configuration file uses http://yaml.org/[YAML] for its syntax. -See the {beats-ref}/config-file-format.html[Config File Format] section of the -_Beats Platform Reference_ for more about the structure of the config file. - -The following topics describe how to configure Filebeat: +include::{libbeat-dir}/shared/configuring-intro.asciidoc[] * <> +* <> * <> * <> * <> @@ -46,6 +33,8 @@ The following topics describe how to configure Filebeat: include::./filebeat-options.asciidoc[] +include::{docdir}/../docs/filebeat-modules-options.asciidoc[] + include::./filebeat-general-options.asciidoc[] include::{libbeat-dir}/shared-path-config.asciidoc[] diff --git a/filebeat/docs/faq.asciidoc b/filebeat/docs/faq.asciidoc index 76c6478aed2..4547e165fb9 100644 --- a/filebeat/docs/faq.asciidoc +++ b/filebeat/docs/faq.asciidoc @@ -17,8 +17,8 @@ effects. For example, changed file identifiers may result in {beatname_uc} readi {beatname_uc} might be incorrectly configured or unable to send events to the output. To resolve the issue: -* Make sure the config file specifies the correct path to the file that you are collecting. See <> -for more information. +* If using modules, make sure the `var.paths` setting points to the file. If +configuring an input manually, make sure the `paths` setting is correct. * Verify that the file is not older than the value specified by <<{beatname_lc}-input-log-ignore-older,`ignore_older`>>. `ignore_older` is disable by default so this depends on the value you have set. You can change this behavior by specifying a different value for <<{beatname_lc}-input-log-ignore-older,`ignore_older`>>. diff --git a/filebeat/docs/filebeat-modules-options.asciidoc b/filebeat/docs/filebeat-modules-options.asciidoc index efbfc603c7f..bba71a69163 100644 --- a/filebeat/docs/filebeat-modules-options.asciidoc +++ b/filebeat/docs/filebeat-modules-options.asciidoc @@ -1,121 +1,75 @@ -:modulename: apache mysql +:modulename: system nginx mysql [id="configuration-{beatname_lc}-modules"] -== Enable and run modules +== Configure modules + +++++ +Modules +++++ NOTE: Using {beatname_uc} modules is optional. You may decide to -<> if you are using +<> if you're using a log type that isn't supported, or you want to use a different setup. -{beatname_uc} <<{beatname_lc}-modules,modules>> provide a quick way for you to get started -processing common log formats. They contain default configurations, -Elasticsearch ingest node pipeline definitions, and Kibana dashboards to help you +{beatname_uc} <<{beatname_lc}-modules,modules>> provide a quick way to +get started processing common log formats. They contain default configurations, +{es} ingest node pipeline definitions, and {kib} dashboards to help you implement and deploy a log monitoring solution. -{beatname_uc} provides a few different ways to enable modules. You can: +You can configure modules in the `modules.d` directory (recommended), or in the +{beatname_uc} configuration file. -* <> -* <> -* <> +Before running {beatname_uc} with modules enabled, make sure you also set up the +environment to use {kib} dashboards. See +<<{beatname_lc}-installation-configuration>> for more information. include::{libbeat-dir}/shared-note-file-permissions.asciidoc[] -When you enable modules, you can also -<> to change the default -behavior of the modules, and you can specify -<> to override input settings. - -Before running {beatname_uc} with modules enabled, make sure you also set up the -environment to use Kibana dashboards. See <<{beatname_lc}-modules-quickstart>> for -more information. - [float] -[[enable-modules-d-configs]] -=== Enable module configs in the `modules.d` directory +[[configure-modules-d-configs]] +=== Configure modules in the `modules.d` directory The `modules.d` directory contains default configurations for all the modules -available in {beatname_uc}. You can enable or disable specific module configurations -under `modules.d` by running the -<> commands. - -For example, to enable the `apache` and `mysql` configs in the `modules.d` -directory, you use: - -include::./include/enable-modules-command.asciidoc[] - -Then when you run {beatname_uc}, it loads the corresponding module configurations -specified in the `modules.d` directory (for example, `modules.d/apache.yml` and -`modules.d/mysql.yml`). +available in {beatname_uc}. To enable or disable specific module configurations +under `modules.d`, run the +<> command. For example: -To see a list of enabled and disabled modules, run: +include::{libbeat-dir}/tab-widgets/enable-modules-widget.asciidoc[] -include::./include/list-modules-command.asciidoc[] +The default configurations assume that your data is in the location expected for +your OS and that the behavior of the module is appropriate for your environment. +To change the default behavior, configure variable settings. For a list of +available settings, see the documentation under <<{beatname_lc}-modules>>. -The default module configurations assume that the logs you’re harvesting are -in the location expected for your OS and that the behavior of the module is -appropriate for your environment. To change the default configurations, you need -to <>. +For advanced use cases, you can also +<>. -[float] -[[enable-modules-cli]] -=== Enable modules when you run {beatname_uc} - -To enable specific <<{beatname_lc}-modules,modules>> when you run {beatname_uc} at the -command line, you can use the `--modules` flag. This approach works well when -you're getting started and want to specify different modules and settings each -time you run {beatname_uc}. Any modules specified at the command line will be loaded +TIP: You can enable modules at runtime by using the +<<{beatname_lc}-modules,--modules flag>>. This is useful if you're getting started +and want to try things out. Any modules specified at the command line are loaded along with any modules that are enabled in the configuration file or `modules.d` directory. If there's a conflict, the configuration specified at the command line is used. -The following command enables and runs the `nginx`,`mysql`, and `system` -modules. - -*deb and rpm:* - -["source","sh",subs="attributes"] ----- -{beatname_lc} --modules nginx,mysql,system ----- - -*mac:* - -["source","sh",subs="attributes"] ----- -./{beatname_lc} --modules nginx,mysql,system ----- - -*win:* - -["source","sh",subs="attributes"] ----- -PS > .{backslash}{beatname_lc}.exe --modules nginx,mysql,system ----- - -The default module configurations assume that the logs you’re harvesting are -in the location expected for your OS and that the behavior of the module is -appropriate for your environment. To change the default configurations, you need -to <>. - [float] -[[enable-modules-config-file]] -=== Enable module configs in the +{beatname_lc}.yml+ file +[[configure-modules-config-file]] +=== Configure modules in the +{beatname_lc}.yml+ file When possible, you should use the config files in the `modules.d` directory. -However, enabling <<{beatname_lc}-modules,modules>> directly in the config file is a -practical approach if you have upgraded from a previous version of {beatname_uc} -and don't want to move your module configs to the `modules.d` directory. You can -continue to configure modules in the +{beatname_lc}.yml+ file, but you won't be -able to use the `modules` command to enable and disable configurations because -the command requires the `modules.d` layout. +However, configuring <<{beatname_lc}-modules,modules>> directly in the config +file is a practical approach if you have upgraded from a previous version of +{beatname_uc} and don't want to move your module configs to the `modules.d` +directory. You can continue to configure modules in the +{beatname_lc}.yml+ +file, but you won't be able to use the `modules` command to enable and disable +configurations because the command requires the `modules.d` layout. -To enable specific modules in the +{beatname_lc}.yml+ config file, you can add +To enable specific modules in the +{beatname_lc}.yml+ config file, add entries to the +{beatname_lc}.modules+ list. Each entry in the list begins with a dash (-) and is followed by settings for that module. The following example shows a configuration that runs the `nginx`,`mysql`, and -`system` modules. +`system` modules: ["source","yaml",subs="attributes"] ---- @@ -125,15 +79,8 @@ The following example shows a configuration that runs the `nginx`,`mysql`, and - module: system ---- -The default module configurations assume that the logs you’re harvesting are -in the location expected for your OS and that the behavior of the module is -appropriate for your environment. To change the default configurations, you need -to <>. - -[[specify-variable-settings]] -=== Configure variable settings - -include::./include/set-paths.asciidoc[] +// Add Javascript and CSS for tabbed panels +include::{libbeat-dir}/tab-widgets/code.asciidoc[] [[advanced-settings]] === Override input settings @@ -175,4 +122,3 @@ You can also enable `close_eof` for all inputs created by any of the modules: ---------------------------------------------------------------------- :modulename!: - diff --git a/filebeat/docs/filebeat-options.asciidoc b/filebeat/docs/filebeat-options.asciidoc index ddb06aeaa34..b6fa7edbe01 100644 --- a/filebeat/docs/filebeat-options.asciidoc +++ b/filebeat/docs/filebeat-options.asciidoc @@ -7,9 +7,7 @@ TIP: <<{beatname_lc}-modules-overview,{beatname_uc} modules>> provide the fastest getting started experience for common log formats. See -<<{beatname_lc}-modules-quickstart>> to learn how to get started with modules. -Also see <> for information about enabling -and configuring modules. +<<{beatname_lc}-installation-configuration>> to learn how to get started. To configure {beatname_uc} manually (instead of using <<{beatname_lc}-modules-overview,modules>>), you specify a list of inputs in the @@ -35,6 +33,28 @@ input type more than once. For example: fields_under_root: true ---- +For the most basic configuration, define a single input with a single path. For +example: + +[source,yaml] +------------------------------------------------------------------------------------- +filebeat.inputs: +- type: log + enabled: true + paths: + - /var/log/*.log +------------------------------------------------------------------------------------- + +The input in this example harvests all files in the path `/var/log/*.log`, which +means that {beatname_uc} will harvest all files in the directory `/var/log/` +that end with `.log`. All patterns supported by +https://golang.org/pkg/path/filepath/#Glob[Go Glob] are also supported here. + +To fetch all files from a predefined level of subdirectories, use this pattern: +`/var/log/*/*.log`. This fetches all `.log` files from the subfolders of +`/var/log`. It does not fetch log files from the `/var/log` folder itself. +Currently it is not possible to recursively fetch all files in all +subdirectories of a directory. [float] [id="{beatname_lc}-input-types"] diff --git a/filebeat/docs/getting-started.asciidoc b/filebeat/docs/getting-started.asciidoc index 5b3972ad671..86e8c6d33d2 100644 --- a/filebeat/docs/getting-started.asciidoc +++ b/filebeat/docs/getting-started.asciidoc @@ -1,293 +1,174 @@ -[[filebeat-getting-started]] -== Get started with {beatname_uc} +:modulename: system nginx mysql -++++ -Get started -++++ - -include::{libbeat-dir}/shared-getting-started-intro.asciidoc[] - -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> - -[[filebeat-installation]] -=== Step 1: Install Filebeat - -include::{libbeat-dir}/shared-download-and-install.asciidoc[] - -[[deb]] -*deb:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes,callouts"] ------------------------------------------------- -curl -L -O https://artifacts.elastic.co/downloads/beats/filebeat/filebeat-{version}-amd64.deb -sudo dpkg -i filebeat-{version}-amd64.deb ------------------------------------------------- - -endif::[] - -[[rpm]] -*rpm:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes,callouts"] ------------------------------------------------- -curl -L -O https://artifacts.elastic.co/downloads/beats/filebeat/filebeat-{version}-x86_64.rpm -sudo rpm -vi filebeat-{version}-x86_64.rpm ------------------------------------------------- - -endif::[] - -[[mac]] -*mac:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes,callouts"] ------------------------------------------------- -curl -L -O https://artifacts.elastic.co/downloads/beats/filebeat/filebeat-{version}-darwin-x86_64.tar.gz -tar xzvf filebeat-{version}-darwin-x86_64.tar.gz ------------------------------------------------- - -endif::[] - -include::{libbeat-dir}/shared-brew-install.asciidoc[] - -[[linux]] -*linux:* +//TODO: Remove release-state override before merging. -ifeval::["{release-state}"=="unreleased"] +[id="{beatname_lc}-installation-configuration"] +== {beatname_uc} quick start: installation and configuration -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes,callouts"] ------------------------------------------------- -curl -L -O https://artifacts.elastic.co/downloads/beats/filebeat/filebeat-{version}-linux-x86_64.tar.gz -tar xzvf filebeat-{version}-linux-x86_64.tar.gz ------------------------------------------------- +++++ +Quick start: installation and configuration +++++ -endif::[] +This guide describes how to get started quickly with log collection. +You'll learn how to: -[[docker]] -*docker:* +* install {beatname_uc} on each system you want to monitor +* specify the location of your log files +* parse log data into fields and send it to {es} +* visualize the log data in {kib} -See <> for deploying Docker containers. +[role="screenshot"] +image::./images/kibana-system.png[{beatname_uc} System dashboard] -[[kubernetes]] -*kubernetes:* +[float] +=== Before you begin -See <> for deploying with Kubernetes. +You need {es} for storing and searching your data, and {kib} for visualizing and +managing it. -[[cloudfoundry]] -*cloudfoundry:* +include::{libbeat-dir}/tab-widgets/spinup-stack-widget.asciidoc[] -See <> for deploying with Cloud Foundry. +[float] +[[installation]] +=== Step 1: Install {beatname_uc} -[[win]] -*win:* +Install {beatname_uc} on all the servers you want to monitor. -ifeval::["{release-state}"=="unreleased"] +To download and install {beatname_uc}, use the commands that work with your +system: -Version {version} of {beatname_uc} has not yet been released. +include::{libbeat-dir}/tab-widgets/install-widget.asciidoc[] -endif::[] +[float] +[[other-installation-options]] +==== Other installation options -ifeval::["{release-state}"!="unreleased"] +* <> +* https://www.elastic.co/downloads/beats/{beatname_lc}[Download page] +* <> +* <> +* <> -. Download the Filebeat Windows zip file from the -https://www.elastic.co/downloads/beats/filebeat[downloads page]. +[float] +[[set-connection]] +=== Step 2: Connect to the {stack} -. Extract the contents of the zip file into `C:\Program Files`. +include::{libbeat-dir}/shared/connecting-to-es.asciidoc[] -. Rename the `filebeat--windows` directory to `Filebeat`. +[float] +[[enable-modules]] +=== Step 3: Enable and configure data collection modules -. Open a PowerShell prompt as an Administrator (right-click the PowerShell icon and select *Run As Administrator*). +{beatname_uc} uses modules to collect and parse log data. -. From the PowerShell prompt, run the following commands to install Filebeat as a -Windows service: +. Identify the modules you need to enable. To see a list of available +<>, run: + -[source,shell] ----------------------------------------------------------------------- -PS > cd 'C:\Program Files\Filebeat' -PS C:\Program Files\Filebeat> .\install-service-filebeat.ps1 ----------------------------------------------------------------------- - -NOTE: If script execution is disabled on your system, you need to set the execution policy for the current session to allow the script to run. For example: `PowerShell.exe -ExecutionPolicy UnRestricted -File .\install-service-filebeat.ps1`. - -endif::[] - -[[filebeat-configuration]] -=== Step 2: Configure Filebeat - -TIP: <> provide the fastest getting -started experience for common log formats. If you are using Filebeat modules, -skip this section, including the remaining getting started steps, and go -directly to <>. - -include::{libbeat-dir}/shared-configuring.asciidoc[] +-- +include::{libbeat-dir}/tab-widgets/list-modules-widget.asciidoc[] +-- ++ +Can't find a module for your file type? Skip this section and +<> manually. -Here is a sample of the `filebeat` section of the `filebeat.yml` file. Filebeat uses predefined -default values for most configuration options. +. From the installation directory, enable one or more modules. For example, the +following command enables the `system`, `nginx`, and `mysql` module +configs: ++ +-- +include::{libbeat-dir}/tab-widgets/enable-modules-widget.asciidoc[] +-- -[source,yaml] -------------------------------------------------------------------------------------- -filebeat.inputs: -- type: log - enabled: true - paths: - - /var/log/*.log - #- c:\programdata\elasticsearch\logs\* -------------------------------------------------------------------------------------- - -To configure Filebeat: - -. Define the path (or paths) to your log files. +. In the module configs under `modules.d`, change the module settings to match +your environment. + -For the most basic Filebeat configuration, you can define a single input with a single path. For example: +For example, log locations are set based on the OS. If your logs aren't in +default locations, set the `paths` variable: + +-- [source,yaml] -------------------------------------------------------------------------------------- -filebeat.inputs: -- type: log - enabled: true - paths: - - /var/log/*.log -------------------------------------------------------------------------------------- -+ -The input in this example harvests all files in the path `/var/log/*.log`, which means -that Filebeat will harvest all files in the directory `/var/log/` that end with `.log`. All patterns supported -by https://golang.org/pkg/path/filepath/#Glob[Go Glob] are also supported here. -+ -To fetch all files from a predefined level of subdirectories, the following pattern can be used: -`/var/log/*/*.log`. This fetches all `.log` files from the subfolders of `/var/log`. It does not -fetch log files from the `/var/log` folder itself. Currently it is not possible to recursively -fetch all files in all subdirectories of a directory. - -include::{libbeat-dir}/step-configure-output.asciidoc[] - -include::{libbeat-dir}/step-configure-kibana-endpoint.asciidoc[] - -include::{libbeat-dir}/step-configure-credentials.asciidoc[] - -include::{libbeat-dir}/step-test-config.asciidoc[] - -include::{libbeat-dir}/step-look-at-config.asciidoc[] - -[[filebeat-template]] -=== Step 3: Load the index template in Elasticsearch +---- +- module: nginx + access: + var.paths: ["/var/log/nginx/access.log*"] <1> +---- +-- -include::{libbeat-dir}/shared-template-load.asciidoc[] +To see the full list of variables for a module, see the documentation under +<>. -[[load-kibana-dashboards]] -=== Step 4: Set up the Kibana dashboards +include::{libbeat-dir}/shared/config-check.asciidoc[] -include::{libbeat-dir}/dashboards.asciidoc[] +[float] +[[setup-assets]] +=== Step 4: Set up assets -[[filebeat-starting]] -=== Step 5: Start Filebeat +{beatname_uc} comes with predefined assets for parsing, indexing, and +visualizing your data. To load these assets: -Start Filebeat by issuing the appropriate command for your platform. If you -are accessing a secured Elasticsearch cluster, make sure you've configured -credentials as described in <<{beatname_lc}-configuration>>. +. Make sure the user specified in +{beatname_lc}.yml+ is +<>. -NOTE: If you use an init.d script to start Filebeat on deb or rpm, you can't -specify command line flags (see <>). To specify flags, -start Filebeat in the foreground. - -*deb and rpm:* - -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -sudo service {beatname_lc} start ----------------------------------------------------------------------- - -*docker:* +. From the installation directory, run: ++ +-- +include::{libbeat-dir}/tab-widgets/setup-widget.asciidoc[] +-- ++ +`-e` is optional and sends output to standard error instead of the configured log output. -See <>. +This step loads the recommended {ref}/indices-templates.html[index template] for writing to {es} +and deploys the sample dashboards for visualizing the data in {kib}. -*mac and linux:* +This step does not load the ingest pipelines used to parse log lines. By +default, ingest pipelines are set up automatically the first time you run the +module and connect to {es}. -[source,shell] ----------------------------------------------------------------------- -sudo chown root filebeat.yml <1> -sudo ./filebeat -e ----------------------------------------------------------------------- -<1> You'll be running Filebeat as root, so you need to change ownership -of the configuration file, or run Filebeat with `--strict.perms=false` -specified. See -{beats-ref}/config-file-permissions.html[Config File Ownership and Permissions] -in the _Beats Platform Reference_. +[TIP] +===== +A connection to {es} (or {ess}) is required to set up the initial +environment. If you're using a different output, such as {ls}, see: -include::{libbeat-dir}/shared-brew-run.asciidoc[] +* <> +* <> +* <> +===== -*win:* +[float] +[[start]] +=== Step 5: Start {beatname_uc} -[source,shell] ----------------------------------------------------------------------- -PS C:\Program Files\Filebeat> Start-Service filebeat ----------------------------------------------------------------------- +Before starting {beatname_uc}, modify the user credentials in ++{beatname_lc}.yml+ and specify a user who is +<>. +To start {beatname_uc}, run: -By default, Windows log files are stored in `C:\ProgramData\filebeat\Logs`. +// tag::start-step[] +:requires-sudo: +include::{libbeat-dir}/tab-widgets/start-widget.asciidoc[] +:requires-sudo!: +// end::start-step[] -Filebeat is now ready to send log files to your defined output. +{beatname_uc} should begin streaming events to {es}. -[[view-kibana-dashboards]] -=== Step 6: View the sample Kibana dashboards +[float] +[[view-data]] +=== Step 6: View your data in {kib} -To make it easier for you to explore Filebeat data in Kibana, we've created -example {beatname_uc} dashboards. You loaded the dashboards earlier when you -ran the `setup` command. +include::{libbeat-dir}/shared/opendashboards.asciidoc[tag=open-dashboards-intro] -include::{libbeat-dir}/opendashboards.asciidoc[] +include::{libbeat-dir}/shared/opendashboards.asciidoc[tag=open-dashboards] -These dashboards are designed to work out-of-the box when you use -<>. However, you can also use them -as examples and {kibana-ref}/dashboard.html[customize] them to meet your needs -even if you aren't using Filebeat modules. +[float] +=== What's next? -To populate the example dashboards with data, you need to either -<> or use Logstash to -parse the data into the fields expected by the dashboards. +Now that you have your logs streaming into {es}, learn how to unify your logs, +metrics, uptime, and application performance data. -// TODO: Add this section back to the docs when the examples are available. -// If you are using Logstash, see the -// {logstash-ref}/logstash-config-for-filebeat-modules.html[configuration examples] -// in the Logstash documentation for help parsing the log formats supported -// by the dashboards. +include::{libbeat-dir}/shared/obs-apps.asciidoc[] -Here is an example of the Filebeat system dashboard: +:modulename!: -[role="screenshot"] -image::./images/kibana-system.png[] +// Add Javascript and CSS for tabbed panels +include::{libbeat-dir}/tab-widgets/code.asciidoc[] diff --git a/filebeat/docs/howto/howto.asciidoc b/filebeat/docs/howto/howto.asciidoc index f83ae0707f4..14675aae3ca 100644 --- a/filebeat/docs/howto/howto.asciidoc +++ b/filebeat/docs/howto/howto.asciidoc @@ -5,28 +5,40 @@ -- Learn how to perform common {beatname_uc} configuration tasks. -* <> +* < +* <<{beatname_lc}-template>> +* <> +* <> +* <> * <<{beatname_lc}-geoip>> * <<{beatname_lc}-deduplication>> -* <> * <> +* <> * <> -- -include::{docdir}/../docs/filebeat-modules-options.asciidoc[] +include::override-config-settings.asciidoc[] + +include::{libbeat-dir}/howto/load-index-templates.asciidoc[] + +include::{libbeat-dir}/howto/change-index-name.asciidoc[] + +include::{libbeat-dir}/howto/load-dashboards.asciidoc[] + +include::load-ingest-pipelines.asciidoc[] include::{libbeat-dir}/shared-geoip.asciidoc[] include::{libbeat-dir}/shared-deduplication.asciidoc[] +include::{libbeat-dir}/shared-config-ingest.asciidoc[] + :standalone: include::{libbeat-dir}/shared-env-vars.asciidoc[] :standalone!: -include::{libbeat-dir}/shared-config-ingest.asciidoc[] - :standalone: include::{libbeat-dir}/yaml.asciidoc[] :standalone!: diff --git a/filebeat/docs/howto/load-ingest-pipelines.asciidoc b/filebeat/docs/howto/load-ingest-pipelines.asciidoc new file mode 100644 index 00000000000..db0e3f00fb3 --- /dev/null +++ b/filebeat/docs/howto/load-ingest-pipelines.asciidoc @@ -0,0 +1,47 @@ +[[load-ingest-pipelines]] +== Load ingest pipelines + +The ingest pipelines used to parse log lines are set up automatically the first +time you run {beatname_uc}, assuming the {es} output is enabled. If you're sending +events to {ls}, or plan to use +<>, you need to +load the ingest pipelines manually. To do this, run the `setup` command with +the `--pipelines` option specified. If you used the +<> command to enable modules in the `modules.d` +directory, also specify the `--modules` flag. For example, the following command +loads the ingest pipelines used by all filesets enabled in the system, nginx, +and mysql modules: + +//TODO: Replace with the platform tab widget. + +*deb and rpm:* + +["source","sh",subs="attributes"] +---- +{beatname_lc} setup --pipelines --modules system,nginx,mysql +---- + +*mac:* + +["source","sh",subs="attributes"] +---- +./{beatname_lc} setup --pipelines --modules system,nginx,mysql +---- + +*linux:* + +["source","sh",subs="attributes"] +---- +./{beatname_lc} setup --pipelines --modules system,nginx,mysql +---- + +*win:* + +["source","sh",subs="attributes"] +---- +PS > .{backslash}{beatname_lc}.exe setup --pipelines --modules system,nginx,mysql +---- + +TIP: If you're loading ingest pipelines manually because you want to send events +to {ls}, also see +{logstash-ref}/filebeat-modules.html[Working with {beatname_uc} modules]. \ No newline at end of file diff --git a/filebeat/docs/howto/override-config-settings.asciidoc b/filebeat/docs/howto/override-config-settings.asciidoc new file mode 100644 index 00000000000..cb69353f00b --- /dev/null +++ b/filebeat/docs/howto/override-config-settings.asciidoc @@ -0,0 +1,77 @@ +[id="override-{beatname_lc}-config-settings"] +== Override configuration settings at the command line + +++++ +Override configuration settings +++++ + +//TODO: Convert this topic to use platform tabs. + +// REVEWERS: This is a mix of new and old content. Please review. + +NOTE: If you're running {beatname_uc} as a service, you can't specify +command-line flags. To specify flags, start {beatname_uc} in the foreground. + +You can override any configuration setting from the command line by using flags: + +`-E, --E "SETTING_NAME=VALUE"`:: +Overrides a specific configuration setting. +`-M, --M "VAR_NAME=VALUE"`:: +Overrides the default configuration for a module. + +You can specify multiple overrides. Overrides are applied to the currently +running {beatname_uc} process. The {beatname_uc} configuration file is not +changed. + +[float] +[[example-override-config]] +=== Example: override configuration file settings + +The following configuration sends logging output to files: + +["source","sh",subs="attributes"] +---- +logging.level: info +logging.to_files: true +logging.files: + path: /var/log/filebeat + name: filebeat + keepfiles: 7 + permissions: 0644 +---- + +To override the logging level and send logging output to standard error instead +of a file, use the `-E` flag when you run {beatname_uc}: + +["source","sh",subs="attributes"] +---- +-E "logging.to_files=false" -E "logging.to_stderr=true" -E "logging.level=error" +---- + +[float] +[[example-override-module-setting]] +=== Example: override module settings + +The following configuration sets the path to Nginx access logs: + +[source,yaml] +---- +- module: nginx + access: + var.paths: ["/var/log/nginx/access.log*"] <1> +---- + +To override this setting from the command line, use the `-M` flag when you run +{beatname_uc}. The variable name must include the module and fileset name. For +example: + +["source","sh",subs="attributes"] +---- +-M "nginx.access.var.paths=[/path/to/log/nginx/access.log*]" +---- + +You can specify multiple overrides. Each override must start with `-M`. + +For information about specific variables that you can set for each fileset, +see the documentation under <<{beatname_lc}-modules>>. + diff --git a/filebeat/docs/images/kibana-created-indexes.png b/filebeat/docs/images/kibana-created-indexes.png deleted file mode 100644 index ff4904bb350..00000000000 Binary files a/filebeat/docs/images/kibana-created-indexes.png and /dev/null differ diff --git a/filebeat/docs/images/kibana-navigation-vis.png b/filebeat/docs/images/kibana-navigation-vis.png deleted file mode 100644 index cb34e1039e4..00000000000 Binary files a/filebeat/docs/images/kibana-navigation-vis.png and /dev/null differ diff --git a/filebeat/docs/include/config-option-intro.asciidoc b/filebeat/docs/include/config-option-intro.asciidoc index d4e16825085..364b111a126 100644 --- a/filebeat/docs/include/config-option-intro.asciidoc +++ b/filebeat/docs/include/config-option-intro.asciidoc @@ -6,9 +6,10 @@ Each fileset has separate variable settings for configuring the behavior of the module. If you don’t specify variable settings, the +{modulename}+ module uses the defaults. -For more information, see <>. Also see +For advanced use cases, you can also override input settings. See <>. TIP: When you specify a setting at the command line, remember to prefix the setting with the module name, for example, +{modulename}.{fileset_ex}.var.paths+ instead of +{fileset_ex}.var.paths+. + diff --git a/filebeat/docs/include/gs-link.asciidoc b/filebeat/docs/include/gs-link.asciidoc index 38b22e54a5d..6c47e8c67d7 100644 --- a/filebeat/docs/include/gs-link.asciidoc +++ b/filebeat/docs/include/gs-link.asciidoc @@ -1,2 +1,2 @@ -TIP: Read the <> to learn how to set up and -run modules. \ No newline at end of file +TIP: Read the <<{beatname_lc}-installation-configuration,quick start>> to learn +how to configure and run modules. \ No newline at end of file diff --git a/filebeat/docs/include/run-command.asciidoc b/filebeat/docs/include/run-command.asciidoc deleted file mode 100644 index 6a43b9bf8f3..00000000000 --- a/filebeat/docs/include/run-command.asciidoc +++ /dev/null @@ -1,45 +0,0 @@ --- -*deb and rpm:* - -["source","sh",subs="attributes"] ----- -service {beatname_lc} start ----- - -*mac:* - -["source","sh",subs="attributes"] ----- -./{beatname_lc} -e ----- - -*brew:* - -["source","sh",subs="attributes"] ----- -{beatname_lc} -e ----- - -*linux:* - -["source","sh",subs="attributes"] ----- -./{beatname_lc} -e ----- - -*win:* - -["source","sh",subs="attributes"] ----- -PS > Start-Service {beatname_lc} ----- - -If the module is configured correctly, you'll see -`INFO Harvester started` messages for each file specified in the config. - -NOTE: Depending on how you've installed {beatname_uc}, you might see errors -related to file ownership or permissions when you try to run {beatname_uc} -modules. See {beats-ref}/config-file-permissions.html[Config File Ownership and -Permissions] in the _Beats Platform Reference_ for more information. - --- diff --git a/filebeat/docs/include/running-modules.asciidoc b/filebeat/docs/include/running-modules.asciidoc deleted file mode 100644 index bc1cef2325f..00000000000 --- a/filebeat/docs/include/running-modules.asciidoc +++ /dev/null @@ -1,43 +0,0 @@ -:has_module_steps: - -[float] -[id="running-{modulename}-modules"] -=== Set up and run the module - -Before doing these steps, verify that {es} and {kib} are running and -that {es} is ready to receive data from {beatname_uc}. - -If you're running our -https://www.elastic.co/cloud/elasticsearch-service[hosted {ess}] on -{ecloud}, or you've enabled security in {es} and {kib}, you need to specify -additional connection information before setting up and running the module. See -<> for the complete setup. - -To set up and run the module: - -. Enable the module: -+ -include::./enable-modules-command.asciidoc[] -+ -This command enables the module config defined in the `modules.d` directory. See -<> for other ways to enable modules. -+ -To see a list of enabled and disabled modules, run: -+ -include::./list-modules-command.asciidoc[] - -. Set up the initial environment: -+ -include::./setup-command.asciidoc[] - -. Run {beatname_uc}. -+ -If your logs aren't in the default location, see -<>, then run {beatname_uc} after you've -set the paths variable. -+ -include::./run-command.asciidoc[] - -include::./visualize-data.asciidoc[] - -:has_module_steps!: diff --git a/filebeat/docs/include/set-paths.asciidoc b/filebeat/docs/include/set-paths.asciidoc deleted file mode 100644 index 6e28d978b45..00000000000 --- a/filebeat/docs/include/set-paths.asciidoc +++ /dev/null @@ -1,59 +0,0 @@ -Each module and fileset has variables that you can set to change the default -behavior of the module, including the paths where the module looks for log -files. You can set the path in configuration or from the command line. For -example: - -[source,yaml] ----- -- module: nginx - access: - var.paths: ["/var/log/nginx/access.log*"] <1> ----- -<1> Sets the path for `nginx` access log files. - -To set the path at the command line, use the `-M` flag. The variable name -must include the module and fileset name. For example: - -*deb and rpm:* - -["source","sh",subs="attributes"] ----- -{beatname_lc} -e -M "nginx.access.var.paths=[/var/log/nginx/access.log*]" ----- - -*mac:* - -["source","sh",subs="attributes"] ----- -./{beatname_lc} -e -M "nginx.access.var.paths=[/usr/local/var/log/nginx/access.log*]" ----- - -*brew:* - -["source","sh",subs="attributes"] ----- -{beatname_lc} -e -M "nginx.access.var.paths=[/usr/local/var/log/nginx/access.log*]" ----- - -*linux:* - -["source","sh",subs="attributes"] ----- -./{beatname_lc} -e -M "nginx.access.var.paths=[/usr/local/var/log/nginx/access.log*]" ----- - -*win:* - -["source","sh",subs="attributes"] ----- -PS > .{backslash}{beatname_lc}.exe -e -M "nginx.access.var.paths=[c:/programdata/nginx/logs/*access.log*]" ----- - -You can specify multiple overrides. Each override must start with `-M`. - -If you are running {beatname_uc} as a service, you cannot set paths from the -command line. You must set the `var.paths` option in the module configuration -file. - -For information about specific variables that you can set for each fileset, -see the <<{beatname_lc}-modules,documentation for the modules>>. diff --git a/filebeat/docs/include/setup-command.asciidoc b/filebeat/docs/include/setup-command.asciidoc deleted file mode 100644 index 68fc66a03d6..00000000000 --- a/filebeat/docs/include/setup-command.asciidoc +++ /dev/null @@ -1,47 +0,0 @@ --- -*deb and rpm:* - -["source","sh",subs="attributes"] ----- -{beatname_lc} setup -e ----- - -*mac:* - -["source","sh",subs="attributes"] ----- -./{beatname_lc} setup -e ----- - -*linux:* - -["source","sh",subs="attributes"] ----- -./{beatname_lc} setup -e ----- - -*brew:* - -["source","sh",subs="attributes"] ----- -{beatname_lc} setup -e ----- - -*win:* - -["source","sh",subs="attributes"] ----- -PS > .{backslash}{beatname_lc}.exe setup -e ----- - -The <> command loads the recommended index template for -writing to {es} and deploys the sample dashboards (if available) for visualizing -the data in {kib}. This is a one-time setup step. - -The `-e` flag is optional and sends output to standard error instead of syslog. - -The ingest pipelines used to parse log lines are set up automatically the first -time you run the module, assuming the {es} output is enabled. If you're sending -events to {ls}, or plan to use <>, also see <>. --- \ No newline at end of file diff --git a/filebeat/docs/include/visualize-data.asciidoc b/filebeat/docs/include/visualize-data.asciidoc deleted file mode 100644 index 5c594725cb4..00000000000 --- a/filebeat/docs/include/visualize-data.asciidoc +++ /dev/null @@ -1,15 +0,0 @@ -ifeval::["{has-dashboards}"=="true"] -. Explore your data in {kib}: -+ -.. Open your browser and navigate to the *Dashboard* overview in {kib}: -http://localhost:5601/app/kibana#/dashboards[http://localhost:5601/app/kibana#/dashboards]. -Replace `localhost` with the name of the {kib} host. If you're using an -https://cloud.elastic.co/[{ecloud}] instance, log in to your cloud account, -then navigate to the {kib} endpoint in your deployment. -.. If necessary, log in with your {kib} username and password. -.. Enter the module name in the search box, then open a dashboard and explore -the visualizations for your parsed logs. -+ -TIP: If you don’t see data in {kib}, try changing the date range to a larger -range. By default, {kib} shows the last 15 minutes. -endif::[] \ No newline at end of file diff --git a/filebeat/docs/index.asciidoc b/filebeat/docs/index.asciidoc index d7341b081b7..d427d5d8a39 100644 --- a/filebeat/docs/index.asciidoc +++ b/filebeat/docs/index.asciidoc @@ -38,10 +38,6 @@ include::./overview.asciidoc[] include::./getting-started.asciidoc[] -include::./modules-getting-started.asciidoc[] - -include::{libbeat-dir}/repositories.asciidoc[] - include::./setting-up-running.asciidoc[] include::./upgrading.asciidoc[] @@ -68,3 +64,4 @@ include::./faq.asciidoc[] include::{libbeat-dir}/contributing-to-beats.asciidoc[] +include::{libbeat-dir}/shared/redirects.asciidoc[] diff --git a/filebeat/docs/modules-getting-started.asciidoc b/filebeat/docs/modules-getting-started.asciidoc deleted file mode 100644 index db621fa6e29..00000000000 --- a/filebeat/docs/modules-getting-started.asciidoc +++ /dev/null @@ -1,142 +0,0 @@ -:has_module_steps: -:modulename: system nginx mysql - -[[filebeat-modules-quickstart]] -=== Quick start: modules for common log formats - -{beatname_uc} provides a set of pre-built modules that you can use to rapidly -implement and deploy a log monitoring solution, complete with sample dashboards -and data visualizations (when available), in about 5 minutes. These modules -support common log formats, such as Nginx, Apache2, and MySQL, and can be run by -issuing a simple command. - -This topic shows you how to run the basic modules with minimal extra -configuration. For detailed documentation and the full list of available -modules, see <>. - -Can't find a module for your log file type? Follow the numbered steps under -<> to set up and configure {beatname_uc} manually. - -==== Prerequisites - -Before running {beatname_uc} modules: - -* Install and configure the Elastic stack. See -{stack-gs}/get-started-elastic-stack.html[Get started with the {stack}]. - -* Complete the {beatname_uc} installation instructions described in -<>. After installing {beatname_uc}, return to this -quick start page. - -* Verify that {es} and {kib} are running and that {es} is -ready to receive data from {beatname_uc}. - -[[running-modules-quickstart]] -==== Running {beatname_uc} modules - -To set up and run {beatname_uc} modules: - -. In the +{beatname_lc}.yml+ config file, set the location of the {es} -installation. By default, {beatname_uc} assumes {es} is running locally on port -9200. -+ -include::{libbeat-dir}/step-configure-output.asciidoc[] - -include::{libbeat-dir}/step-configure-credentials.asciidoc[] - -. Enable the modules you want to run. For example, the following command enables -the system, nginx, and mysql modules: -+ -include::./include/enable-modules-command.asciidoc[] -+ -This command enables the module configs defined in the `modules.d` directory. See -<> for other ways to enable modules. -+ -To see a list of enabled and disabled modules, run: -+ -include::./include/list-modules-command.asciidoc[] - -. Set up the initial environment: -+ -include::./include/setup-command.asciidoc[] - -. Run {beatname_uc}. -+ -If your logs aren't in the default location, -<> before running {beatname_uc}. -+ -include::./include/run-command.asciidoc[] - -include::./include/visualize-data.asciidoc[] - -[[example-dashboard]] -==== Example dashboard - -Here's an example of the syslog dashboard: - -image::./images/kibana-system.png[Syslog dashboard] - - -[[setting-variables]] -==== Set the paths variable - -The examples here assume that the logs you're harvesting are in the location -expected for your OS and that the default behavior of {beatname_uc} is appropriate -for your environment. - -include::./include/set-paths.asciidoc[] - -See <> for more information about setting -variables and advanced options. - -[[load-ingest-pipelines]] -==== Load ingest pipelines manually - -The ingest pipelines used to parse log lines are set up automatically the first -time you run the module, assuming the {es} output is enabled. If you're sending -events to {ls}, or plan to use -<>, you need to -load the ingest pipelines manually. To do this, run the `setup` command with -the `--pipelines` option specified. If you used the -<> command to enable modules in the `modules.d` -directory, also specify the `--modules` flag. For example, the following command -loads the ingest pipelines used by all filesets enabled in the system, nginx, -and mysql modules: - -// override modulename attribute so it works with the --modules option -:modulename: system,nginx,mysql - -*deb and rpm:* - -["source","sh",subs="attributes"] ----- -{beatname_lc} setup --pipelines --modules {modulename} ----- - -*mac:* - -["source","sh",subs="attributes"] ----- -./{beatname_lc} setup --pipelines --modules {modulename} ----- - -*linux:* - -["source","sh",subs="attributes"] ----- -./{beatname_lc} setup --pipelines --modules {modulename} ----- - -*win:* - -["source","sh",subs="attributes"] ----- -PS > .{backslash}{beatname_lc}.exe setup --pipelines --modules {modulename} ----- - -TIP: If you're loading ingest pipelines manually because you want to send events -to {ls}, also see -{logstash-ref}/filebeat-modules.html[Working with {beatname_uc} modules]. - -:has_module_steps!: -:modulename!: diff --git a/filebeat/docs/modules-overview.asciidoc b/filebeat/docs/modules-overview.asciidoc index 62654f44cd7..008a16c0d87 100644 --- a/filebeat/docs/modules-overview.asciidoc +++ b/filebeat/docs/modules-overview.asciidoc @@ -13,26 +13,23 @@ the following: The {beatname_uc} configuration is also responsible with stitching together multiline events when needed. -* Elasticsearch {ref}/ingest.html[Ingest Node] pipeline definition, +* {es} {ref}/ingest.html[Ingest Node] pipeline definition, which is used to parse the log lines. -* Fields definitions, which are used to configure Elasticsearch with the +* Fields definitions, which are used to configure {es} with the correct types for each field. They also contain short descriptions for each of the fields. -* Sample Kibana dashboards, when available, that can be used to visualize the +* Sample {kib} dashboards, when available, that can be used to visualize the log files. {beatname_uc} automatically adjusts these configurations based on your environment -and loads them to the respective Elastic stack components. - -{beatname_uc} modules require Elasticsearch 5.2 or later. +and loads them to the respective {stack} components. [float] === Get started To learn how to configure and run {beatname_uc} modules: -* Get started by reading <>. -* Learn about the different ways to enable modules in <>. -* Dive into the documentation for each module. +* Get started by reading <<{beatname_lc}-installation-configuration>>. +* Dive into the documentation for each <>. diff --git a/filebeat/docs/modules/crowdstrike.asciidoc b/filebeat/docs/modules/crowdstrike.asciidoc index 5e21311674b..e3508c0feca 100644 --- a/filebeat/docs/modules/crowdstrike.asciidoc +++ b/filebeat/docs/modules/crowdstrike.asciidoc @@ -10,36 +10,19 @@ This file is generated! See scripts/docs_collector.py == Crowdstrike module -This is the filebeat module for the Crowdstrike Falcon using the Falcon https://www.crowdstrike.com/blog/tech-center/integrate-with-your-siem[SIEM Connector]. This module collects this data, converts it to ECS, and ingests it to view in the SIEM. By default, the Falcon SIEM connector outputs JSON formatted Falcon Streaming API event data. +This is the {beatname_uc} module for CrowdStrike Falcon using the Falcon https://www.crowdstrike.com/blog/tech-center/integrate-with-your-siem[SIEM Connector]. This module collects this data, converts it to ECS, and ingests it to view in the SIEM. By default, the Falcon SIEM connector outputs JSON formatted Falcon Streaming API event data. This module segments events forwarded by the Falcon SIEM connector into two datasets for endpoint data and Falcon platform audit data. include::../include/what-happens.asciidoc[] +include::../include/gs-link.asciidoc[] + [float] === Compatibility This input supports Crowdstrike Falcon SIEM-Connector-v2.0. -include::../include/running-modules.asciidoc[] - -[float] -=== Dashboards - -The best way to view Crowdstrike events and alert data is in the SIEM. - -[role="screenshot"] -image::./images/siem-alerts-cs.jpg[] - -[float] -For alerts, go to Detections -> External alerts. - -[role="screenshot"] -image::./images/siem-events-cs.jpg[] - -[float] -And for all over event Crowdstrike Falcon event types, go to Host -> Events. - include::../include/configuring-intro.asciidoc[] :fileset_ex: falcon_endpoint @@ -61,6 +44,24 @@ var: include::../include/var-paths.asciidoc[] +[float] +=== Dashboards + +The best way to view CrowdStrike events and alert data is in the SIEM. + +[role="screenshot"] +image::./images/siem-alerts-cs.jpg[] + +[float] +For alerts, go to Detections -> External alerts. + +[role="screenshot"] +image::./images/siem-events-cs.jpg[] + +[float] +And for all over event CrowdStrike Falcon event types, go to Host -> Events. + + :has-dashboards!: :modulename!: diff --git a/filebeat/docs/overview.asciidoc b/filebeat/docs/overview.asciidoc index def183159e9..e45acb4a69a 100644 --- a/filebeat/docs/overview.asciidoc +++ b/filebeat/docs/overview.asciidoc @@ -1,10 +1,6 @@ [[filebeat-overview]] == Filebeat overview -++++ -Overview -++++ - {beatname_uc} is a lightweight shipper for forwarding and centralizing log data. Installed as an agent on your servers, {beatname_uc} monitors the log files or locations that you specify, collects log events, and forwards them diff --git a/filebeat/docs/reload-configuration.asciidoc b/filebeat/docs/reload-configuration.asciidoc index 5ff3fa9ac37..10a706d4020 100644 --- a/filebeat/docs/reload-configuration.asciidoc +++ b/filebeat/docs/reload-configuration.asciidoc @@ -62,7 +62,7 @@ same time, it can lead to unexpected behavior. For module configurations, you specify the `path` option in the +{beatname_lc}.config.modules+ section of the +{beatname_lc}.yml+ file. By default, {beatname_uc} loads the module configurations enabled in the -<> directory. For example: +<> directory. For example: ["source","sh",subs="attributes"] ------------------------------------------------------------------------------ diff --git a/filebeat/docs/setting-up-running.asciidoc b/filebeat/docs/setting-up-running.asciidoc index 5968b3f571d..f81ebee9297 100644 --- a/filebeat/docs/setting-up-running.asciidoc +++ b/filebeat/docs/setting-up-running.asciidoc @@ -11,17 +11,21 @@ Set up and run ++++ -Before reading this section, see the -<<{beatname_lc}-getting-started,getting started documentation>> for basic +Before reading this section, see +<<{beatname_lc}-installation-configuration>> for basic installation instructions to get you started. -This section includes additional information on how to set up and run +This section includes additional information on how to install, set up, and run {beatname_uc}, including: * <> +* <> + * <> +* <> + * <> * <> @@ -30,6 +34,10 @@ This section includes additional information on how to set up and run * <> +* <<{beatname_lc}-starting>> + +* <> + //MAINTAINERS: If you add a new file to this section, make sure you update the bulleted list ^^ too. @@ -39,6 +47,8 @@ include::{libbeat-dir}/keystore.asciidoc[] include::{libbeat-dir}/command-reference.asciidoc[] +include::{libbeat-dir}/repositories.asciidoc[] + include::./running-on-docker.asciidoc[] include::./running-on-kubernetes.asciidoc[] @@ -47,4 +57,6 @@ include::./running-on-cloudfoundry.asciidoc[] include::{libbeat-dir}/shared-systemd.asciidoc[] -include::{libbeat-dir}/shared-shutdown.asciidoc[] +include::{libbeat-dir}/shared/start-beat.asciidoc[] + +include::{libbeat-dir}/shared/shutdown.asciidoc[] diff --git a/filebeat/docs/upgrading.asciidoc b/filebeat/docs/upgrading.asciidoc index 428be52e04d..ca5aa0cfbe8 100644 --- a/filebeat/docs/upgrading.asciidoc +++ b/filebeat/docs/upgrading.asciidoc @@ -5,7 +5,7 @@ Upgrade ++++ -For information about upgrading to a new version, see the following topics in the _Beats Platform Reference_: +For information about upgrading to a new version, see: * {beats-ref}/breaking-changes.html[Breaking Changes] * {beats-ref}/upgrading.html[Upgrade] diff --git a/heartbeat/docs/configuring-howto.asciidoc b/heartbeat/docs/configuring-howto.asciidoc index 0a2b6fc5729..0f8d8a83444 100644 --- a/heartbeat/docs/configuring-howto.asciidoc +++ b/heartbeat/docs/configuring-howto.asciidoc @@ -7,23 +7,7 @@ Configure ++++ -Before modifying configuration settings, make sure you've completed the -<> in the Getting Started. -This section describes some common use cases for changing configuration options. - -To configure Heartbeat, you edit the configuration file. For rpm and deb, -you’ll find the default configuration file at -+/etc/heartbeat/heartbeat.yml+. There's also a full example -configuration file at +/etc/heartbeat/heartbeat.reference.yml+ that shows -all non-deprecated options. For mac and win, look in the archive that you -extracted. - -The Heartbeat configuration file uses http://yaml.org/[YAML] for its syntax. -See the -{beats-ref}/config-file-format.html[Config File Format] section of the -_Beats Platform Reference_ for more about the structure of the config file. - -The following topics describe how to configure Heartbeat: +include::{libbeat-dir}/shared/configuring-intro.asciidoc[] * <> * <> diff --git a/heartbeat/docs/getting-started.asciidoc b/heartbeat/docs/getting-started.asciidoc index d6f9782ec02..38857a227ca 100644 --- a/heartbeat/docs/getting-started.asciidoc +++ b/heartbeat/docs/getting-started.asciidoc @@ -1,22 +1,31 @@ -[[heartbeat-getting-started]] -== Get started with {beatname_uc} +[id="{beatname_lc}-installation-configuration"] +== {beatname_uc} quick start: installation and configuration ++++ -Get started +Quick start: installation and configuration ++++ -include::{libbeat-dir}/shared-getting-started-intro.asciidoc[] +This guide describes how to get started quickly collecting uptime data about +your hosts. You'll learn how to: -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* install {beatname_uc} +* specify the protocols to monitor +* send uptime data to {es} +* visualize the uptime data in {kib} +[role="screenshot"] +image::./images/heartbeat-statistics.png[{beatname_uc} HTTP monitoring dashboard] + +[float] +=== Before you begin + +You need {es} for storing and searching your data, and {kib} for visualizing and +managing it. -[[heartbeat-installation]] +include::{libbeat-dir}/tab-widgets/spinup-stack-widget.asciidoc[] + +[float] +[[installation]] === Step 1: Install Heartbeat Unlike most Beats, which you install on edge nodes, you typically install @@ -24,161 +33,38 @@ Heartbeat as part of a monitoring service that runs on a separate machine and possibly even outside of the network where the services that you want to 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. - -include::{libbeat-dir}/shared-download-and-install.asciidoc[] - -[[deb]] -*deb:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -curl -L -O {downloads}/heartbeat/heartbeat-{version}-amd64.deb -sudo dpkg -i heartbeat-{version}-amd64.deb ----------------------------------------------------------------------- - -endif::[] - -[[rpm]] -*rpm:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -curl -L -O {downloads}/heartbeat/heartbeat-{version}-x86_64.rpm -sudo rpm -vi heartbeat-{version}-x86_64.rpm ----------------------------------------------------------------------- - -endif::[] - -[[mac]] -*mac:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes"] ------------------------------------------------- -curl -L -O {downloads}/heartbeat/heartbeat-{version}-darwin-x86_64.tar.gz -tar xzvf heartbeat-{version}-darwin-x86_64.tar.gz ------------------------------------------------- - -endif::[] - -include::{libbeat-dir}/shared-brew-install.asciidoc[] - -[[linux]] -*linux:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes"] ------------------------------------------------- -curl -L -O {downloads}/heartbeat/heartbeat-{version}-linux-x86_64.tar.gz -tar xzvf heartbeat-{version}-linux-x86_64.tar.gz ------------------------------------------------- -endif::[] - -[[docker]] -*docker:* - -See <> for deploying Docker containers. - -[[win]] -*win:* - -ifeval::["{release-state}"=="unreleased"] +To download and install {beatname_uc}, use the commands that work with your +system: -Version {version} of {beatname_uc} has not yet been released. +include::{libbeat-dir}/tab-widgets/install-widget.asciidoc[] -endif::[] +[float] +[[other-installation-options]] +==== Other installation options -ifeval::["{release-state}"!="unreleased"] +* <> +* https://www.elastic.co/downloads/beats/{beatname_lc}[Download page] +* <> -. Download the Heartbeat Windows zip file from the -https://www.elastic.co/downloads/beats/heartbeat[downloads page]. +[float] +[[set-connection]] +=== Step 2: Connect to the {stack} -. Extract the contents of the zip file into `C:\Program Files`. +include::{libbeat-dir}/shared/connecting-to-es.asciidoc[] -. Rename the +heartbeat--windows+ directory to +Heartbeat+. - -. Open a PowerShell prompt as an Administrator (right-click the PowerShell icon -and select *Run As Administrator*). - -. From the PowerShell prompt, run the following commands to install Heartbeat as -a Windows service: -+ -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -PS > cd 'C:\Program Files\Heartbeat' -PS C:\Program Files\Heartbeat> .\install-service-heartbeat.ps1 ----------------------------------------------------------------------- - -NOTE: If script execution is disabled on your system, you need to set the -execution policy for the current session to allow the script to run. For -example: -+PowerShell.exe -ExecutionPolicy UnRestricted -File .\install-service-heartbeat.ps1+. - -endif::[] - -Before starting Heartbeat, you should look at the configuration options in -the configuration file, for example +C:\Program Files\Heartbeat\heartbeat.yml+ -or +/etc/heartbeat/heartbeat.yml+. For more information about these -options, see <>. - -[[heartbeat-configuration]] -=== Step 2: Configure Heartbeat - -include::{libbeat-dir}/shared-configuring.asciidoc[] +[float] +[[configuration]] +=== Step 3: Configure Heartbeat monitors Heartbeat provides monitors to check the status of hosts at set intervals. -You configure each monitor individually. Heartbeat currently provides monitors -for ICMP, TCP, and HTTP (see <> for more about these -monitors). Here is an example that configures Heartbeat to use an `icmp` -monitor: +Heartbeat currently provides monitors for ICMP, TCP, and HTTP (see +<> for more about these monitors). -[source,yaml] ----------------------------------------------------------------------- -heartbeat.monitors: -- type: icmp - schedule: '*/5 * * * * * *' - hosts: ["myhost"] -output.elasticsearch: - hosts: ["myEShost:9200"] ----------------------------------------------------------------------- +You configure each monitor individually. In +{beatname_lc}.yml+, specify the +list of monitors that you want to enable. Each item in the list begins with a +dash (-). The following example configures Heartbeat to use two monitors, an +`icmp` monitor and a `tcp` monitor: -To configure Heartbeat: - -. Specify the list of monitors that you want to enable. Each item in the list -begins with a dash (-). The following example configures Heartbeat to use two -monitors, an `icmp` monitor and a `tcp` monitor: -+ [source,yaml] ---------------------------------------------------------------------- heartbeat.monitors: @@ -198,88 +84,75 @@ was started. Heartbeat adds the `@every` keyword to the syntax provided by the `cronexpr` package. <3> The `mode` specifies whether to ping one IP (`any`) or all resolvable IPs (`all`). -+ -See <> for a full description of each -configuration option. - -include::{libbeat-dir}/step-configure-output.asciidoc[] - -include::{libbeat-dir}/step-configure-kibana-endpoint.asciidoc[] -include::{libbeat-dir}/step-configure-credentials.asciidoc[] +include::{libbeat-dir}/shared/config-check.asciidoc[] -include::{libbeat-dir}/step-test-config.asciidoc[] +[float] +[[setup-assets]] +=== Step 4: Set up assets -include::{libbeat-dir}/step-look-at-config.asciidoc[] +{beatname_uc} comes with predefined assets for parsing, indexing, and +visualizing your data. To load these assets: -[[heartbeat-template]] -=== Step 3: Load the index template in Elasticsearch +. Make sure the user specified in +{beatname_lc}.yml+ is +<>. -include::{libbeat-dir}/shared-template-load.asciidoc[] - -[[load-kibana-dashboards]] -=== Step 4: Set up the Kibana dashboards - -Dashboards for Heartbeat can be found in the https://github.com/elastic/uptime-contrib[uptime-contrib] github repository. - -[[heartbeat-starting]] +. From the installation directory, run: ++ +-- +include::{libbeat-dir}/tab-widgets/setup-widget.asciidoc[] +-- ++ +`-e` is optional and sends output to standard error instead of the configured log output. + +This step loads the recommended {ref}/indices-templates.html[index template] for writing to {es}. +It does not install {beatname_uc} dashboards. Heartbeat dashboards and +installation steps are available in the +https://github.com/elastic/uptime-contrib[uptime-contrib] GitHub repository. + +[TIP] +===== +A connection to {es} (or {ess}) is required to set up the initial +environment. If you're using a different output, such as {ls}, see +<>. +===== + +[float] +[[start]] === Step 5: Start Heartbeat -Start Heartbeat by issuing the appropriate command for your platform. If you -are accessing a secured Elasticsearch cluster, make sure you've configured -credentials as described in <<{beatname_lc}-configuration>>. - -NOTE: If you use an init.d script to start Heartbeat on deb or rpm, you can't -specify command line flags (see <>). To specify flags, -start Heartbeat in the foreground. - -*deb and rpm:* - -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -sudo service {beatname_lc}-elastic start ----------------------------------------------------------------------- - -*mac and linux:* +Before starting {beatname_uc}, modify the user credentials in ++{beatname_lc}.yml+ and specify a user who is +<>. -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -sudo chown root heartbeat.yml <1> -sudo ./heartbeat -e ----------------------------------------------------------------------- -<1> You'll be running Heartbeat as root, so you need to change ownership of the -configuration file, or run Heartbeat with `--strict.perms=false` specified. See -{beats-ref}/config-file-permissions.html[Config File Ownership and Permissions] -in the _Beats Platform Reference_. +To start {beatname_uc}, run: :requires-sudo: -include::{libbeat-dir}/shared-brew-run.asciidoc[] +include::{libbeat-dir}/tab-widgets/start-widget.asciidoc[] :requires-sudo!: -*win:* +Heartbeat is now ready to check the status of your services and send +events to your defined output. -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -PS C:\Program Files\Heartbeat> Start-Service heartbeat ----------------------------------------------------------------------- +[float] +[[view-data]] +=== Step 6: View your data in {kib} -By default, Windows log files are stored in +C:\ProgramData\heartbeat\Logs+. +{beatname_uc} comes with pre-built {kib} dashboards and UIs for visualizing the +status of your services. The dashboards are available in the +https://github.com/elastic/uptime-contrib[uptime-contrib] GitHub repository. -Heartbeat is now ready to check the status of your services and send -events to your defined output. +If you loaded the dashboards earlier, open them now. -[[view-kibana-dashboards]] -=== Step 6: View the sample Kibana dashboards +include::{libbeat-dir}/shared/opendashboards.asciidoc[tag=open-dashboards] -To make it easier for you to visualize the status of your services, we have -created example {beatname_uc} dashboards in the -https://github.com/elastic/uptime-contrib[uptime-contrib] github repository. If -you loaded them earlier, open them now. +[float] +=== What's next? -include::{libbeat-dir}/opendashboards.asciidoc[] +Now that you have your uptime data streaming into {es}, learn how to unify your +logs, metrics, uptime, and application performance data. -The dashboards are provided as examples. We recommend that you -{kibana-ref}/dashboard.html[customize] them to meet your needs. +include::{libbeat-dir}/shared/obs-apps.asciidoc[] -[role="screenshot"] -image::./images/heartbeat-statistics.png[Heartbeat statistics] +// Add Javascript and CSS for tabbed panels +include::{libbeat-dir}/tab-widgets/code.asciidoc[] diff --git a/heartbeat/docs/howto/howto.asciidoc b/heartbeat/docs/howto/howto.asciidoc index ce19ba208d3..dfaa11b68d4 100644 --- a/heartbeat/docs/howto/howto.asciidoc +++ b/heartbeat/docs/howto/howto.asciidoc @@ -6,6 +6,8 @@ Learn how to perform common {beatname_uc} configuration tasks. * <> +* <<{beatname_lc}-template>> +* <> * <<{beatname_lc}-geoip>> * <> * <> @@ -16,6 +18,10 @@ Learn how to perform common {beatname_uc} configuration tasks. include::{docdir}/heartbeat-observer-options.asciidoc[] +include::{libbeat-dir}/howto/load-index-templates.asciidoc[] + +include::{libbeat-dir}/howto/change-index-name.asciidoc[] + include::{libbeat-dir}/shared-geoip.asciidoc[] :standalone: diff --git a/heartbeat/docs/images/heartbeat-statistics.png b/heartbeat/docs/images/heartbeat-statistics.png index 80c83bade79..1d77386407a 100644 Binary files a/heartbeat/docs/images/heartbeat-statistics.png and b/heartbeat/docs/images/heartbeat-statistics.png differ diff --git a/heartbeat/docs/images/kibana-created-indexes.png b/heartbeat/docs/images/kibana-created-indexes.png deleted file mode 100644 index 606ba267d68..00000000000 Binary files a/heartbeat/docs/images/kibana-created-indexes.png and /dev/null differ diff --git a/heartbeat/docs/images/kibana-navigation-vis.png b/heartbeat/docs/images/kibana-navigation-vis.png deleted file mode 100644 index 039af9e5746..00000000000 Binary files a/heartbeat/docs/images/kibana-navigation-vis.png and /dev/null differ diff --git a/heartbeat/docs/index.asciidoc b/heartbeat/docs/index.asciidoc index 63f84333a2a..6da2775949f 100644 --- a/heartbeat/docs/index.asciidoc +++ b/heartbeat/docs/index.asciidoc @@ -33,8 +33,6 @@ include::./overview.asciidoc[] include::./getting-started.asciidoc[] -include::{libbeat-dir}/repositories.asciidoc[] - include::./setting-up-running.asciidoc[] include::./configuring-howto.asciidoc[] @@ -53,3 +51,4 @@ include::./faq.asciidoc[] include::{libbeat-dir}/contributing-to-beats.asciidoc[] +include::{libbeat-dir}/shared/redirects.asciidoc[] diff --git a/heartbeat/docs/overview.asciidoc b/heartbeat/docs/overview.asciidoc index 2dd97907117..b1bdd33b2b6 100644 --- a/heartbeat/docs/overview.asciidoc +++ b/heartbeat/docs/overview.asciidoc @@ -1,10 +1,6 @@ [[heartbeat-overview]] == Heartbeat overview -++++ -Overview -++++ - Heartbeat is a lightweight daemon that you install on a remote server to periodically check the status of your services and determine whether they are available. Unlike {metricbeat-ref}/index.html[Metricbeat], which only tells you if diff --git a/heartbeat/docs/setting-up-running.asciidoc b/heartbeat/docs/setting-up-running.asciidoc index 9808c01bc7f..4acaaa6ffea 100644 --- a/heartbeat/docs/setting-up-running.asciidoc +++ b/heartbeat/docs/setting-up-running.asciidoc @@ -11,17 +11,21 @@ Set up and run ++++ -Before reading this section, see the -<<{beatname_lc}-getting-started,getting started documentation>> for basic +Before reading this section, see +<<{beatname_lc}-installation-configuration>> for basic installation instructions to get you started. -This section includes additional information on how to set up and run +This section includes additional information on how to install, set up, and run {beatname_uc}, including: * <> +* <> + * <> +* <> + * <> * <> @@ -34,8 +38,10 @@ include::{libbeat-dir}/keystore.asciidoc[] include::{libbeat-dir}/command-reference.asciidoc[] +include::{libbeat-dir}/repositories.asciidoc[] + include::./running-on-docker.asciidoc[] include::{libbeat-dir}/shared-systemd.asciidoc[] -include::{libbeat-dir}/shared-shutdown.asciidoc[] +include::{libbeat-dir}/shared/shutdown.asciidoc[] diff --git a/journalbeat/docs/configuring-howto.asciidoc b/journalbeat/docs/configuring-howto.asciidoc index f3ce587285b..c813fa2d151 100644 --- a/journalbeat/docs/configuring-howto.asciidoc +++ b/journalbeat/docs/configuring-howto.asciidoc @@ -7,13 +7,7 @@ Configure ++++ -Before modifying configuration settings, make sure you've completed the -<<{beatname_lc}-configuration,configuration steps>> in the Getting Started. -This section describes some common use cases for changing configuration options. - -include::{libbeat-dir}/shared-configuring.asciidoc[] - -The following topics describe how to configure {beatname_uc}: +include::{libbeat-dir}/shared/configuring-intro.asciidoc[] * <> * <> diff --git a/journalbeat/docs/getting-started.asciidoc b/journalbeat/docs/getting-started.asciidoc index 7d90caa49ad..ddcf0e47038 100644 --- a/journalbeat/docs/getting-started.asciidoc +++ b/journalbeat/docs/getting-started.asciidoc @@ -1,120 +1,63 @@ -[id="{beatname_lc}-getting-started"] -== Get started with {beatname_uc} +[id="{beatname_lc}-installation-configuration"] +== {beatname_uc} quick start: installation and configuration ++++ -Get started +Quick start: installation and configuration ++++ -include::{libbeat-dir}/shared-getting-started-intro.asciidoc[] +This guide describes how to get started quickly with log data collection from +systemd journals. You'll learn how to: -* <<{beatname_lc}-installation>> -* <<{beatname_lc}-configuration>> -* <<{beatname_lc}-template>> -* <<{beatname_lc}-starting>> -* <> -* <> +* install {beatname_uc} on each system you want to monitor +* specify the location of your log files +* parse log data into fields and send it to {es} +* visualize the log data in {kib} -[id="{beatname_lc}-installation"] -=== Step 1: Install {beatname_uc} - -include::{libbeat-dir}/shared-download-and-install.asciidoc[] - -[[deb]] -*deb:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes"] ------------------------------------------------- -curl -L -O https://artifacts.elastic.co/downloads/beats/{beatname_lc}/{beatname_lc}-{version}-amd64.deb -sudo dpkg -i {beatname_lc}-{version}-amd64.deb ------------------------------------------------- - -endif::[] - -[[rpm]] -*rpm:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes"] ------------------------------------------------- -curl -L -O https://artifacts.elastic.co/downloads/beats/{beatname_lc}/{beatname_lc}-{version}-x86_64.rpm -sudo rpm -vi {beatname_lc}-{version}-x86_64.rpm ------------------------------------------------- - -endif::[] - -[[linux]] -*linux:* +[float] +=== Before you begin -ifeval::["{release-state}"=="unreleased"] +You need {es} for storing and searching your data, and {kib} for visualizing and +managing it. -Version {version} of {beatname_uc} has not yet been released. +include::{libbeat-dir}/tab-widgets/spinup-stack-widget.asciidoc[] -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes"] ------------------------------------------------- -curl -L -O https://artifacts.elastic.co/downloads/beats/{beatname_lc}/{beatname_lc}-{version}-linux-x86_64.tar.gz -tar xzvf {beatname_lc}-{version}-linux-x86_64.tar.gz ------------------------------------------------- - -endif::[] - -[[docker]] -*docker:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. +[float] +[[install]] +=== Step 1: Install {beatname_uc} -endif::[] +Install {beatname_uc} on all the servers you want to monitor. -ifeval::["{release-state}"!="unreleased"] +To download and install {beatname_uc}, use the commands that work with your +system: -See <> for deploying Docker containers. +include::{libbeat-dir}/tab-widgets/install-deb-rpm-linux-widget.asciidoc[] -endif::[] +[float] +[[other-installation-options]] +==== Other installation options -[id="{beatname_lc}-configuration"] -=== Step 2: Configure {beatname_uc} +* <> +* https://www.elastic.co/downloads/beats/{beatname_lc}[Download page] +* <> -Before running {beatname_uc}, you can specify the location of the systemd -journal files and configure how you want the files to be read. If you accept the -default configuration, {beatname_uc} reads from the local journal. +[float] +[[set-connection]] +=== Step 2: Connect to the {stack} -include::{libbeat-dir}/shared-configuring.asciidoc[] +include::{libbeat-dir}/shared/connecting-to-es.asciidoc[] -Here is a sample of the +{beatname_lc}+ section of the +{beatname_lc}.yml+ file. -{beatname_uc} uses predefined default values for most configuration options. -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -journalbeat.inputs: -- paths: ["/path/to/journal/directory"] - seek: head ----------------------------------------------------------------------- +[float] +[[configuration]] +=== Step 3: Configure {beatname_uc} -To configure {beatname_uc}: +Before running {beatname_uc}, specify the location of the systemd journal files +and configure how you want the files to be read. If you accept the default +configuration, {beatname_uc} reads from the local journal. -. Specify a list of paths to your systemd journal files. Each path can be a -directory path (to collect events from all journals in a directory), or a file -path. For example: +. In +{beatname_lc}.yml+, specify a list of paths to your systemd journal files. +Each path can be a directory path (to collect events from all journals in a +directory), or a file path. For example: + ["source","sh",subs="attributes"] ---- @@ -122,6 +65,7 @@ path. For example: - paths: - "/dev/log" - "/var/log/messages/my-journal-file.journal" + seek: head ---- + If no paths are specified, {beatname_uc} reads from the default journal. @@ -148,75 +92,78 @@ Redis events from a Docker container tagged as `redis`, use: - "_COMM=redis" ---- -include::{libbeat-dir}/step-configure-output.asciidoc[] - -include::{libbeat-dir}/step-configure-kibana-endpoint.asciidoc[] +include::{libbeat-dir}/shared/config-check.asciidoc[] -include::{libbeat-dir}/step-configure-credentials.asciidoc[] +[float] +[[setup-assets]] +=== Step 4: Set up assets -include::{libbeat-dir}/step-test-config.asciidoc[] +{beatname_uc} comes with predefined assets for parsing, indexing, and +visualizing your data. To load these assets: -include::{libbeat-dir}/step-look-at-config.asciidoc[] +. Make sure the user specified in +{beatname_lc}.yml+ is +<>. +. From the installation directory, run: ++ +-- +include::{libbeat-dir}/tab-widgets/setup-deb-rpm-linux-widget.asciidoc[] +-- ++ +`-e` is optional and sends output to standard error instead of the configured log output. -[id="{beatname_lc}-template"] -=== Step 3: Load the index template in {es} +This step loads the recommended {ref}/indices-templates.html[index template] for writing to {es}. -include::{libbeat-dir}/shared-template-load.asciidoc[] +[TIP] +===== +A connection to {es} (or {ess}) is required to set up the initial +environment. If you're using a different output, such as {ls}, see +<>. +===== -[id="{beatname_lc}-starting"] +[float] +[[start]] === Step 5: Start {beatname_uc} -Start {beatname_uc} by issuing the appropriate command for your platform. If you -are accessing a secured {es} cluster, make sure you've configured -credentials as described in <<{beatname_lc}-configuration>>. +Before starting {beatname_uc}, modify the user credentials in ++{beatname_lc}.yml+ and specify a user who is +<>. -NOTE: If you use an init.d script to start {beatname_uc} on deb or rpm, you can't -specify command line flags (see <>). To specify flags, -start {beatname_uc} in the foreground. +To start {beatname_uc}, run: -*deb and rpm:* +// tag::start-step[] +include::{libbeat-dir}/tab-widgets/start-deb-rpm-linux-widget.asciidoc[] +// end::start-step[] -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -sudo service {beatname_lc} start ----------------------------------------------------------------------- +{beatname_uc} is now ready to send journal events to the {es}. -*linux:* +[float] +[[view-data]] +=== Step 6: View your data in {kib} -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -sudo chown root {beatname_lc}.yml <1> -sudo ./{beatname_lc} -e ----------------------------------------------------------------------- -<1> You'll be running {beatname_uc} as root, so you need to change ownership -of the configuration file, or run {beatname_uc} with `--strict.perms=false` -specified. See -{beats-ref}/config-file-permissions.html[Config File Ownership and Permissions] -in the _Beats Platform Reference_. - -{beatname_uc} is now ready to send journal events to the defined output. - -[[view-kibana-dashboards]] -=== Step 6: Explore your data in {kib} - -The {beatname_uc} dashboard is currently broken. To start exploring your data, -go to the Discover application in {kib}. From there, you can submit search +There is currently no dashboard available for {beatname_uc}. To start exploring +your data, go to the Discover app in {kib}. From there, you can submit search queries, filter the search results, and view document data. To learn how to build visualizations and dashboards to view your data, see the _{kibana-ref}/index.html[{kib} User Guide]_. -[role="xpack"] -==== Want to tail logs in real time? -Use the Logs app in {kib}. -For more details, see the {logs-guide}[Logs Monitoring Guide]. +[float] +=== What's next? + +Now that you have your logs streaming into {es}, learn how to unify your logs, +metrics, uptime, and application performance data. -The Logs app shows logs -from `filebeat-*` indices by default. To show {beatname_uc} indices, configure -the source to include `journalbeat-*`. You can do this in the Logs app when you -configure the source, or you can modify the {kib} configuration. For example: +include::{libbeat-dir}/shared/obs-apps.asciidoc[] + +[TIP] +==== +The {logs-app} shows logs from `filebeat-*` indices by default. To show +{beatname_uc} indices, configure the source to include `journalbeat-*`. You can +do this in the {logs-app} when you configure the source, or you can modify the {kib} +configuration. For +example: [source,yaml] ---- @@ -225,3 +172,7 @@ xpack.infra: default: logAlias: "filebeat-*,journalbeat-*" ---- +==== + +// Add Javascript and CSS for tabbed panels +include::{libbeat-dir}/tab-widgets/code.asciidoc[] diff --git a/journalbeat/docs/howto/howto.asciidoc b/journalbeat/docs/howto/howto.asciidoc index cf6f9b2199b..14a26a59c1a 100644 --- a/journalbeat/docs/howto/howto.asciidoc +++ b/journalbeat/docs/howto/howto.asciidoc @@ -5,6 +5,8 @@ -- Learn how to perform common {beatname_uc} configuration tasks. +* <<{beatname_lc}-template>> +* <> * <<{beatname_lc}-geoip>> * <> * <> @@ -13,6 +15,9 @@ Learn how to perform common {beatname_uc} configuration tasks. -- +include::{libbeat-dir}/howto/load-index-templates.asciidoc[] + +include::{libbeat-dir}/howto/change-index-name.asciidoc[] include::{libbeat-dir}/shared-geoip.asciidoc[] diff --git a/journalbeat/docs/images/kibana-created-indexes.png b/journalbeat/docs/images/kibana-created-indexes.png deleted file mode 100644 index 0906a90e71c..00000000000 Binary files a/journalbeat/docs/images/kibana-created-indexes.png and /dev/null differ diff --git a/journalbeat/docs/images/kibana-navigation-vis.png b/journalbeat/docs/images/kibana-navigation-vis.png deleted file mode 100644 index 881157e7a1b..00000000000 Binary files a/journalbeat/docs/images/kibana-navigation-vis.png and /dev/null differ diff --git a/journalbeat/docs/index.asciidoc b/journalbeat/docs/index.asciidoc index 94d680c7a5e..390b5134e3e 100644 --- a/journalbeat/docs/index.asciidoc +++ b/journalbeat/docs/index.asciidoc @@ -28,8 +28,6 @@ include::./overview.asciidoc[] include::./getting-started.asciidoc[] -include::{libbeat-dir}/repositories.asciidoc[] - include::./setting-up-running.asciidoc[] include::./configuring-howto.asciidoc[] @@ -46,3 +44,4 @@ include::./troubleshooting.asciidoc[] include::./faq.asciidoc[] +include::{libbeat-dir}/shared/redirects.asciidoc[] diff --git a/journalbeat/docs/overview.asciidoc b/journalbeat/docs/overview.asciidoc index 332dd624234..645aa87ca48 100644 --- a/journalbeat/docs/overview.asciidoc +++ b/journalbeat/docs/overview.asciidoc @@ -1,10 +1,6 @@ [id="{beatname_lc}-overview"] == {beatname_uc} overview -++++ -Overview -++++ - {beatname_uc} is a lightweight shipper for forwarding and centralizing log data from https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html[systemd journals]. Installed as an agent on your servers, {beatname_uc} monitors the journal diff --git a/journalbeat/docs/setting-up-running.asciidoc b/journalbeat/docs/setting-up-running.asciidoc index 265e4d8fae8..ef95d59b8ff 100644 --- a/journalbeat/docs/setting-up-running.asciidoc +++ b/journalbeat/docs/setting-up-running.asciidoc @@ -11,19 +11,22 @@ Set up and run ++++ -Before reading this section, see the -<<{beatname_lc}-getting-started,getting started documentation>> for basic +Before reading this section, see +<<{beatname_lc}-installation-configuration>> for basic installation instructions to get you started. -This section includes additional information on how to set up and run +This section includes additional information on how to install, set up, and run {beatname_uc}, including: * <> * <> * <> +* <> * <> -* <> * <> +* <<{beatname_lc}-starting>> +* <> + //MAINTAINERS: If you add a new file to this section, make sure you update the bulleted list ^^ too. @@ -33,8 +36,12 @@ include::{libbeat-dir}/keystore.asciidoc[] include::{libbeat-dir}/command-reference.asciidoc[] +include::{libbeat-dir}/repositories.asciidoc[] + include::./running-on-docker.asciidoc[] include::{libbeat-dir}/shared-systemd.asciidoc[] -include::{libbeat-dir}/shared-shutdown.asciidoc[] +include::{libbeat-dir}/shared/start-beat.asciidoc[] + +include::{libbeat-dir}/shared/shutdown.asciidoc[] diff --git a/libbeat/docs/command-reference.asciidoc b/libbeat/docs/command-reference.asciidoc index 9ce860eb3eb..bb6a3e7762b 100644 --- a/libbeat/docs/command-reference.asciidoc +++ b/libbeat/docs/command-reference.asciidoc @@ -1059,10 +1059,14 @@ details. Sets the path for log files. See the <> section for details. *`--strict.perms`*:: -Sets strict permission checking on configuration files. The default is -`-strict.perms=true`. See -{beats-ref}/config-file-permissions.html[Config file ownership and permissions] in -the _Beats Platform Reference_ for more information. +Sets strict permission checking on configuration files. The default is `-strict.perms=true`. +ifndef::apm-server[] +See {beats-ref}/config-file-permissions.html[Config file ownership and permissions] +for more information. +endif::[] +ifdef::apm-server[] +See <> for more information. +endif::[] *`-v, --v`*:: Logs INFO-level messages. diff --git a/libbeat/docs/getting-started.asciidoc b/libbeat/docs/getting-started.asciidoc new file mode 100644 index 00000000000..b1a85fddb46 --- /dev/null +++ b/libbeat/docs/getting-started.asciidoc @@ -0,0 +1,17 @@ +[[getting-started]] +== Get started with {beats} + +Each Beat is a separately installable product. To learn how to get started, see: + +* {auditbeat-ref}/auditbeat-installation-configuration.html[Auditbeat] +* {filebeat-ref}/filebeat-installation-configuration.html[Filebeat] +* {functionbeat-ref}/functionbeat-installation-configuration.html[Functionbeat] +* {heartbeat-ref}/heartbeat-installation-configuration.html[Heartbeat] +* {journalbeat-ref}/journalbeat-installation-configuration.html[Journalbeat] +* {metricbeat-ref}/metricbeat-installation-configuration.html[Metricbeat] +* {packetbeat-ref}/packetbeat-installation-configuration.html[Packetbeat] +* {winlogbeat-ref}/winlogbeat-installation-configuration.html[Winlogbeat] + +If you're planning to use the {metrics-app} or the {logs-app} in {kib}, +also see the {metrics-guide}[Metrics Monitoring Guide] +and the {logs-guide}[Logs Monitoring Guide]. diff --git a/libbeat/docs/gettingstarted.asciidoc b/libbeat/docs/gettingstarted.asciidoc deleted file mode 100644 index 4df199ace71..00000000000 --- a/libbeat/docs/gettingstarted.asciidoc +++ /dev/null @@ -1,31 +0,0 @@ -[[getting-started]] -== Get started with {beats} - -Each Beat is a separately installable product. Before installing Beats, you need -to install and configure the {stack}. To learn how to get up and running -quickly, see {stack-gs}/get-started-elastic-stack.html[Get started with the -{stack}]. - -[TIP] -============== -You can skip having to install {es} and {kib} by using our -https://www.elastic.co/cloud/elasticsearch-service[hosted {ess}] on -{ecloud}. The {ess} is available on AWS, GCP, and Azure. -{ess-trial}[Try out the {ess} -for free]. -============== - -After installing the {stack}, see the {beats} getting started guides: - -* {auditbeat-ref}/auditbeat-getting-started.html[Auditbeat] -* {filebeat-ref}/filebeat-getting-started.html[Filebeat] -* {functionbeat-ref}/functionbeat-getting-started.html[Functionbeat] -* {heartbeat-ref}/heartbeat-getting-started.html[Heartbeat] -* {journalbeat-ref}/journalbeat-getting-started.html[Journalbeat] -* {metricbeat-ref}/metricbeat-getting-started.html[Metricbeat] -* {packetbeat-ref}/packetbeat-getting-started.html[Packetbeat] -* {winlogbeat-ref}/winlogbeat-getting-started.html[Winlogbeat] - -If you're planning to use the Metrics app or the Logs app in {kib}, -also see the {metrics-guide}[Metrics Monitoring Guide] -and the {logs-guide}[Logs Monitoring Guide]. diff --git a/libbeat/docs/howto/change-index-name.asciidoc b/libbeat/docs/howto/change-index-name.asciidoc new file mode 100644 index 00000000000..a08292eebd1 --- /dev/null +++ b/libbeat/docs/howto/change-index-name.asciidoc @@ -0,0 +1,43 @@ +[id="change-index-name"] +== Change the index name + +ifndef::no_ilm[] +TIP: If you're sending events to a cluster that supports index lifecycle +management, see <> to learn how to change the index name. +endif::no_ilm[] + +{beatname_uc} uses time series indices, by default, when index lifecycle +management is disabled or unsupported. The indices are named ++{beatname_lc}-{version}-yyyy.MM.dd+, where `yyyy.MM.dd` is the date when the +events were indexed. To use a different name, set the +<> option in the {es} output. The value that +you specify should include the root name of the index plus version and date +information. You also need to configure the `setup.template.name` and +`setup.template.pattern` options to match the new name. For example: + +["source","sh",subs="attributes,callouts"] +----- +output.elasticsearch.index: "customname-%{[{beat_version_key}]}-%{+yyyy.MM.dd}" +setup.template.name: "customname" +setup.template.pattern: "customname-*" +----- + +ifndef::no_ilm[] +WARNING: If <> is enabled (which is typically the default), `setup.template.name` and `setup.template.pattern` are ignored. +endif::no_ilm[] + +ifndef::no_dashboards[] +If you're using pre-built Kibana dashboards, also set the +`setup.dashboards.index` option. For example: + +[source, yaml] +---- +setup.dashboards.index: "customname-*" +---- +endif::no_dashboards[] + +For a full list of template setup options, see <>. + +ifdef::no_dashboards[] +Remember to change the index name when you load dashboards via the Kibana UI. +endif::no_dashboards[] diff --git a/libbeat/docs/dashboards.asciidoc b/libbeat/docs/howto/load-dashboards.asciidoc similarity index 95% rename from libbeat/docs/dashboards.asciidoc rename to libbeat/docs/howto/load-dashboards.asciidoc index 7bdb706095c..781789d3ae4 100644 --- a/libbeat/docs/dashboards.asciidoc +++ b/libbeat/docs/howto/load-dashboards.asciidoc @@ -9,9 +9,12 @@ //// include::../../libbeat/docs/dashboards.asciidoc[] ////////////////////////////////////////////////////////////////////////// +[[load-kibana-dashboards]] +== Load {kib} dashboards + ifdef::has_solutions[] TIP: For deeper observability into your infrastructure, you can use the -Metrics app and the Logs app in {kib}. +{metrics-app} and the {logs-app} in {kib}. For more details, see the {metrics-guide}[Metrics Monitoring Guide] and the {logs-guide}[Logs Monitoring Guide]. endif::has_solutions[] @@ -25,11 +28,11 @@ command (as described here) or +{beatname_lc}.yml+ config file. This requires a Kibana endpoint configuration. If you didn't already configure -a Kibana endpoint, see <<{beatname_lc}-configuration,configure {beatname_uc}>>. +a Kibana endpoint, see <>. Make sure Kibana is running before you perform this step. If you are accessing a secured Kibana instance, make sure you've configured credentials as described in -<<{beatname_lc}-configuration>>. +the <<{beatname_lc}-installation-configuration>>. To set up the Kibana dashboards for {beatname_uc}, use the appropriate command for your system. The command shown here loads the dashboards from the {beatname_uc} @@ -42,7 +45,7 @@ If you've configured the Logstash output, see endif::[] ifdef::requires-sudo[] -include::../../libbeat/docs/shared-note-sudo.asciidoc[] +include::{libbeat-dir}/shared-note-sudo.asciidoc[] endif::requires-sudo[] ifdef::deb_os,rpm_os[] @@ -106,8 +109,9 @@ PS > .{backslash}{beatname_lc}.exe setup --dashboards endif::win_os[] ifndef::no-output-logstash[] +[float] [[load-dashboards-logstash]] -==== Set up dashboards for Logstash output +=== Load dashboards for Logstash output During dashboard loading, {beatname_uc} connects to Elasticsearch to check version information. To load dashboards when the Logstash output is enabled, you diff --git a/libbeat/docs/shared-template-load.asciidoc b/libbeat/docs/howto/load-index-templates.asciidoc similarity index 61% rename from libbeat/docs/shared-template-load.asciidoc rename to libbeat/docs/howto/load-index-templates.asciidoc index 07d0010672f..0cdd4ed80fb 100644 --- a/libbeat/docs/shared-template-load.asciidoc +++ b/libbeat/docs/howto/load-index-templates.asciidoc @@ -1,128 +1,94 @@ -////////////////////////////////////////////////////////////////////////// -//// This content is shared by all Elastic Beats. Make sure you keep the -//// descriptions here generic enough to work for all Beats that include -//// this file. When using cross references, make sure that the cross -//// references resolve correctly for any files that include this one. -//// Use the appropriate variables defined in the index.asciidoc file to -//// resolve Beat names: beatname_uc and beatname_lc -//// Use the following include to pull this content into a doc file: -//// include::../../libbeat/docs/shared-template-load.asciidoc[] -//// This content must be embedded underneath a level 3 heading. -////////////////////////////////////////////////////////////////////////// +[id="{beatname_lc}-template"] +== Load the {es} index template -ifndef::no-output-logstash[] -NOTE: A connection to Elasticsearch is required to load the index template. If -the output is not Elasticsearch, you must -<>. -endif::[] +{es} uses {ref}/indices-templates.html[index templates] to define: -In Elasticsearch, {ref}/indices-templates.html[index -templates] are used to define settings and mappings that determine how fields -should be analyzed. +* Settings that control the behavior of your indices. The settings include the +lifecycle policy used to manage indices as they grow and age. +* Mappings that determine how fields are analyzed. Each mapping sets the +{ref}/mapping-types.html[{es} datatype] to use for a specific data field. The recommended index template file for {beatname_uc} is installed by the {beatname_uc} packages. If you accept the default configuration in the +{beatname_lc}.yml+ config file, {beatname_uc} loads the template automatically -after successfully connecting to Elasticsearch. If the template already exists, +after successfully connecting to {es}. If the template already exists, it's not overwritten unless you configure {beatname_uc} to do so. -[[load-template-auto]] -==== Configure template loading +ifndef::no-output-logstash[] +NOTE: A connection to {es} is required to load the index template. If +the output is not {es} (or {ess}), you must +<>. +endif::[] -By default, {beatname_uc} automatically loads the recommended template file, -+fields.yml+, if the Elasticsearch output is enabled. If you want to use the -default index template, no additional configuration is required. Otherwise, you -can change the defaults in the +{beatname_lc}.yml+ config file -to: +This page shows how to change the default template loading behavior to: + +* <> +* <> +* <> +* <> + +For a full list of template setup options, see <>. + +[float] +[[load-custom-template]] +=== Load your own index template + +To load your own index template, set the following options: -* **Load a different template** -+ [source,yaml] ----- setup.template.name: "your_template_name" setup.template.fields: "path/to/fields.yml" ----- -+ + If the template already exists, it’s not overwritten unless you configure {beatname_uc} to do so. -* **Overwrite an existing template** -+ +[float] +[[overwrite-template]] +=== Overwrite an existing index template + +To overwrite a template that's already loaded into {es}, set: + [source,yaml] ----- setup.template.overwrite: true ----- -* **Disable automatic template loading** -+ +[float] +[[disable-template-loading]] +=== Disable automatic index template loading + +You may want to disable automatic template loading if you're using an output +other than {es} and need to load the template manually. To disable automatic +template loading, set: + [source,yaml] ----- setup.template.enabled: false ----- -+ -If you disable automatic template loading, you need to -<>. - -* **Change the index name** -ifndef::no_ilm[] -+ -TIP: If you're sending events to a cluster that supports index lifecycle -management, see <> to learn how to change the index name. -endif::no_ilm[] -+ -{beatname_uc} uses time series indices, by default, when index lifecycle -management is disabled or unsupported. The indices are named -+{beatname_lc}-{version}-yyyy.MM.dd+, where `yyyy.MM.dd` is the date when the -events were indexed. To use a different name, you set the -<> option in the Elasticsearch output. The value that -you specify should include the root name of the index plus version and date -information. You also need to configure the `setup.template.name` and -`setup.template.pattern` options to match the new name. For example: -+ -["source","sh",subs="attributes,callouts"] ------ -output.elasticsearch.index: "customname-%{[{beat_version_key}]}-%{+yyyy.MM.dd}" -setup.template.name: "customname" -setup.template.pattern: "customname-*" ------ -WARNING: If <> is enabled (which is typically the default), `setup.template.name` and `setup.template.pattern` are ignored. - -ifndef::no_dashboards[] -+ -If you're using pre-built Kibana dashboards, also set the -`setup.dashboards.index` option. For example: -+ -[source, yaml] ----- -setup.dashboards.index: "customname-*" ----- -endif::no_dashboards[] - -ifdef::no_dashboards[] -Remember to change the index name when you load dashboards via the Kibana UI. -endif::no_dashboards[] - -See <> for the full list of configuration options. +If you disable automatic template loading, you must load the index template +manually. +[float] [[load-template-manually]] -==== Load the template manually +=== Load the index template manually -To load the template manually, run the <> command. A -connection to Elasticsearch is required. If another output is enabled, you need -to temporarily disable that output and enable Elasticsearch by using the `-E` -option. +To load the index template manually, run the <> command. +A connection to {es} is required. If another output is enabled, you need to +temporarily disable that output and enable {es} by using the `-E` option. ifndef::no-output-logstash[] The examples here assume that Logstash output is enabled. endif::[] -You can omit the `-E` flags if Elasticsearch output is already enabled. +You can omit the `-E` flags if {es} output is already enabled. -If you are connecting to a secured Elasticsearch cluster, make sure you've -configured credentials as described in <<{beatname_lc}-configuration>>. +If you are connecting to a secured {es} cluster, make sure you've +configured credentials as described in the <<{beatname_lc}-installation-configuration>>. If the host running {beatname_uc} does not have direct connectivity to -Elasticsearch, see <>. +{es}, see <>. ifndef::win_only[] To load the template, use the appropriate command for your system. @@ -141,7 +107,7 @@ ifdef::no-output-logstash[] endif::[] ifdef::requires-sudo[] -include::./shared-note-sudo.asciidoc[] +include::{libbeat-dir}/shared-note-sudo.asciidoc[] endif::requires-sudo[] ifdef::deb_os,rpm_os[] @@ -204,10 +170,11 @@ PS > .{backslash}{beatname_lc}.exe setup --index-management{disable_logstash} -E ---------------------------------------------------------------------- endif::win_os[] +[float] [[force-kibana-new]] -===== Force Kibana to look at newest documents +==== Force Kibana to look at newest documents -If you've already used {beatname_uc} to index data into Elasticsearch, +If you've already used {beatname_uc} to index data into {es}, the index may contain old documents. After you load the index template, you can delete the old documents from +{beatname_lc}-*+ to force Kibana to look at the newest documents. @@ -256,11 +223,12 @@ This command deletes all indices that match the pattern +{beat_default_index_pre Before running this command, make sure you want to delete all indices that match the pattern. +[float] [[load-template-manually-alternate]] -==== Load the template manually (alternate method) +=== Load the index template manually (alternate method) If the host running {beatname_uc} does not have direct connectivity to -Elasticsearch, you can export the index template to a file, move it to a +{es}, you can export the index template to a file, move it to a machine that does have connectivity, and then install the template manually. To export the index template, run: diff --git a/libbeat/docs/images/kibana-created-indexes.png b/libbeat/docs/images/kibana-created-indexes.png deleted file mode 100644 index 08939e91450..00000000000 Binary files a/libbeat/docs/images/kibana-created-indexes.png and /dev/null differ diff --git a/libbeat/docs/images/kibana-navigation-vis.png b/libbeat/docs/images/kibana-navigation-vis.png deleted file mode 100644 index 913db9e737e..00000000000 Binary files a/libbeat/docs/images/kibana-navigation-vis.png and /dev/null differ diff --git a/libbeat/docs/index.asciidoc b/libbeat/docs/index.asciidoc index 5d1309e4f88..97ecaac49c6 100644 --- a/libbeat/docs/index.asciidoc +++ b/libbeat/docs/index.asciidoc @@ -22,7 +22,7 @@ include::./overview.asciidoc[] include::./communitybeats.asciidoc[] -include::./gettingstarted.asciidoc[] +include::./getting-started.asciidoc[] include::./config-file-format.asciidoc[] diff --git a/libbeat/docs/monitoring/monitoring-metricbeat.asciidoc b/libbeat/docs/monitoring/monitoring-metricbeat.asciidoc index afac9852133..d0cf30c9ed5 100644 --- a/libbeat/docs/monitoring/monitoring-metricbeat.asciidoc +++ b/libbeat/docs/monitoring/monitoring-metricbeat.asciidoc @@ -92,9 +92,9 @@ endif::[] === Install and configure {metricbeat} to collect monitoring data ifeval::["{beatname_lc}"!="metricbeat"] -. {metricbeat-ref}/metricbeat-installation.html[Install {metricbeat}] on the -same server as {beatname_uc}. If you already have {metricbeat} installed on the -server, skip this step. +. Install {metricbeat} on the same server as {beatname_uc}. To learn how, see +{metricbeat-ref}/metricbeat-installation-configuration.html[Get started with {metricbeat}]. +If you already have {metricbeat} installed on the server, skip this step. endif::[] ifeval::["{beatname_lc}"=="metricbeat"] . The next step depends on how you want to run {metricbeat}: @@ -103,11 +103,9 @@ take the the steps required for your environment to run two instances of {metricbeat} as a service. The steps for doing this vary by platform and are beyond the scope of this documentation. * If you're running the binary directly in the foreground and want to run a -separate monitoring instance, -{metricbeat-ref}/metricbeat-installation.html[install {metricbeat}] to a -different path. If necessary, set `path.config`, `path.data`, and `path.log` -to point to the correct directories. See <> for the default -locations. +separate monitoring instance, install {metricbeat} to a different path. If +necessary, set `path.config`, `path.data`, and `path.log` to point to the +correct directories. See <> for the default locations. endif::[] . Enable the `beat-xpack` module in {metricbeat}. + diff --git a/libbeat/docs/opendashboards.asciidoc b/libbeat/docs/opendashboards.asciidoc deleted file mode 100644 index 50ec99f15c9..00000000000 --- a/libbeat/docs/opendashboards.asciidoc +++ /dev/null @@ -1,33 +0,0 @@ -////////////////////////////////////////////////////////////////////////// -//// This content is shared by all Elastic Beats. Make sure you keep the -//// descriptions here generic enough to work for all Beats that include -//// this file. When using cross references, make sure that the cross -//// references resolve correctly for any files that include this one. -//// Use the appropriate variables defined in the index.asciidoc file to -//// resolve Beat names: beatname_uc and beatname_lc. -//// Use the following include to pull this content into a doc file: -//// include::../../libbeat/docs/opendashboards.asciidoc[] -////////////////////////////////////////////////////////////////////////// - -To open the dashboards, launch the {kib} web interface by pointing your browser -to port 5601. For example, http://localhost:5601[http://localhost:5601]. -Replace `localhost` with the name of the {kib} host. If you're using our -https://www.elastic.co/cloud/elasticsearch-service[hosted {ess}] instance, log -in to your cloud account, then navigate to the {kib} endpoint in your -deployment. - -In the side navigation, click *Discover*. To see {beatname_uc} data, make sure -the predefined +{beatname_lc}-*+ index pattern is selected. - -[role="screenshot"] -image::./images/kibana-created-indexes.png[Discover tab with index selected] - -TIP: If you don’t see data in {kib}, try changing the date range to a larger -range. By default, {kib} shows the last 15 minutes. - -In the side navigation, click *Dashboard*, then select the dashboard that you -want to open. - -[role="screenshot"] -image::./images/kibana-navigation-vis.png[Navigation widget in Kibana] - diff --git a/libbeat/docs/overview.asciidoc b/libbeat/docs/overview.asciidoc index c44c92a7d87..c28047243a6 100644 --- a/libbeat/docs/overview.asciidoc +++ b/libbeat/docs/overview.asciidoc @@ -1,10 +1,6 @@ [[beats-reference]] == Beats overview -++++ -Overview -++++ - {beats} are open source data shippers that you install as agents on your servers to send operational data to https://www.elastic.co/products/elasticsearch[{es}]. Elastic provides {beats} @@ -31,7 +27,7 @@ To get started, see <>. Want to get up and running quickly with infrastructure metrics monitoring and centralized log analytics? -Try out the Metrics app and the Logs app in {kib}. +Try out the {metrics-app} and the {logs-app} in {kib}. For more details, see the {metrics-guide}[Metrics Monitoring Guide] and the {logs-guide}[Logs Monitoring Guide]. diff --git a/libbeat/docs/shared-beats-attributes.asciidoc b/libbeat/docs/shared-beats-attributes.asciidoc index 093f1bcc8ec..4a285b4759c 100644 --- a/libbeat/docs/shared-beats-attributes.asciidoc +++ b/libbeat/docs/shared-beats-attributes.asciidoc @@ -17,3 +17,4 @@ :beat_version_key: agent.version :access_role: {beat_default_index_prefix}_reader :repo: Beats +:release-state: released diff --git a/libbeat/docs/shared-brew-run.asciidoc b/libbeat/docs/shared-brew-run.asciidoc index ff6d37bad73..23b5a7c4cca 100644 --- a/libbeat/docs/shared-brew-run.asciidoc +++ b/libbeat/docs/shared-brew-run.asciidoc @@ -25,14 +25,13 @@ service, run: ifndef::has_modules_command[] ["source","sh",subs="attributes"] ----- -sudo chown root /usr/local/etc/{beatname_lc}/beatname_lc.yml <1> +sudo chown root /usr/local/etc/{beatname_lc}/{beatname_lc}.yml <1> sudo {beatname_lc} -e ----- <1> You'll be running {beatname_uc} as root, so you need to change ownership of the configuration file, or run {beatname_uc} with `--strict.perms=false` specified. See -{beats-ref}/config-file-permissions.html[Config File Ownership and Permissions] -in the _Beats Platform Reference_. +{beats-ref}/config-file-permissions.html[Config File Ownership and Permissions]. endif::has_modules_command[] ifdef::has_modules_command[] @@ -45,8 +44,7 @@ sudo {beatname_lc} -e <1> You'll be running {beatname_uc} as root, so you need to change ownership of the configuration file and any configurations enabled in the `modules.d` directory, or run {beatname_uc} with `--strict.perms=false` specified. See -{beats-ref}/config-file-permissions.html[Config File Ownership and Permissions] -in the _Beats Platform Reference_. +{beats-ref}/config-file-permissions.html[Config File Ownership and Permissions]. endif::has_modules_command[] diff --git a/libbeat/docs/shared-download-and-install.asciidoc b/libbeat/docs/shared-download-and-install.asciidoc deleted file mode 100644 index 5eabb2cbd02..00000000000 --- a/libbeat/docs/shared-download-and-install.asciidoc +++ /dev/null @@ -1,21 +0,0 @@ - -*Before you begin*: If you haven't installed the {stack}, do that now. See -{stack-gs}/get-started-elastic-stack.html[Get started with the {stack}]. - -To download and install {beatname_uc}, use the commands that work with your -system. - -ifeval::["{release-state}"!="unreleased"] - -ifndef::no_repos[] -[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. -================================================== -endif::no_repos[] - -endif::[] diff --git a/libbeat/docs/shared-getting-started-intro.asciidoc b/libbeat/docs/shared-getting-started-intro.asciidoc deleted file mode 100644 index e0200fd8533..00000000000 --- a/libbeat/docs/shared-getting-started-intro.asciidoc +++ /dev/null @@ -1,26 +0,0 @@ - -To get started with your own {beatname_uc} setup, install and configure these -related products: - -* {es} for storing and indexing the data. -* {kib} for the UI. -ifndef::no-output-logstash[] -* {ls} (optional) for parsing and enhancing the data. -endif::[] - -See {stack-gs}/get-started-elastic-stack.html[Get started with the {stack}] -for more information about installing these products. - -[TIP] -============== -You can skip having to install {es} and {kib} by using our -https://www.elastic.co/cloud/elasticsearch-service[hosted {ess}] on -{ecloud}. The {ess} is available on AWS, GCP, and Azure. -{ess-trial}[Try out the {ess} -for free]. -============== - -After installing the {stack}, read the following topics to learn how to -install, configure, and run {beatname_uc}. Upgrading to a new version of -{beatname_uc}? Start by reading the Beats {beats-ref}/upgrading.html[upgrade -documentation]. diff --git a/libbeat/docs/shared-note-file-permissions.asciidoc b/libbeat/docs/shared-note-file-permissions.asciidoc index 62e1f075e76..43d4c49a9b2 100644 --- a/libbeat/docs/shared-note-file-permissions.asciidoc +++ b/libbeat/docs/shared-note-file-permissions.asciidoc @@ -1,4 +1,3 @@ NOTE: On systems with POSIX file permissions, all Beats configuration files are subject to ownership and file permission checks. For more information, see -{beats-ref}/config-file-permissions.html[Config File Ownership and Permissions] in -the _Beats Platform Reference_. +{beats-ref}/config-file-permissions.html[Config File Ownership and Permissions]. diff --git a/libbeat/docs/shared-shutdown.asciidoc b/libbeat/docs/shared-shutdown.asciidoc deleted file mode 100644 index c1b5c5128c7..00000000000 --- a/libbeat/docs/shared-shutdown.asciidoc +++ /dev/null @@ -1,24 +0,0 @@ -////////////////////////////////////////////////////////////////////////// -//// This content is shared by all Elastic Beats. Make sure you keep the -//// descriptions here generic enough to work for all Beats that include -//// this file. When using cross references, make sure that the cross -//// references resolve correctly for any files that include this one. -//// Use the appropriate variables defined in the index.asciidoc file to -//// resolve Beat names: beatname_uc and beatname_lc. -//// Use the following include to pull this content into a doc file: -//// include::../../libbeat/docs/shared-shutdown.asciidoc[] -////////////////////////////////////////////////////////////////////////// - -[[shutdown]] -=== Stop {beatname_uc} - -An orderly shutdown of {beatname_uc} ensures that it has a chance to clean up -and close outstanding resources. You can help ensure an orderly shutdown by -stopping {beatname_uc} properly. - -If you’re running {beatname_uc} as a service, you can stop it via the service -management functionality provided by your installation. - -If you’re running {beatname_uc} directly in the console, you can stop it by -entering *Ctrl-C*. Alternatively, send SIGTERM to the {beatname_uc} process on a -POSIX system. \ No newline at end of file diff --git a/libbeat/docs/shared/README.txt b/libbeat/docs/shared/README.txt new file mode 100644 index 00000000000..171bbe7e270 --- /dev/null +++ b/libbeat/docs/shared/README.txt @@ -0,0 +1,6 @@ +The content in this folder is shared by all Elastic Beats. If you modify these +files, make sure the content is valid in all Beats that include the files. +Use conditional blocks, if necessary, to wrap content. When using cross +references, make sure the cross references resolve correctly. Use the +appropriate variables defined in the index.asciidoc file to resolve Beat names: +{beatname_uc} and {beatname_lc}. diff --git a/libbeat/docs/step-test-config.asciidoc b/libbeat/docs/shared/config-check.asciidoc similarity index 68% rename from libbeat/docs/step-test-config.asciidoc rename to libbeat/docs/shared/config-check.asciidoc index fb0378b1a16..1db38fc2683 100644 --- a/libbeat/docs/step-test-config.asciidoc +++ b/libbeat/docs/shared/config-check.asciidoc @@ -15,5 +15,15 @@ your config files are in the path expected by {beatname_uc} (see file. Depending on your OS, you might run into file ownership issues when you run this test. See {beats-ref}/config-file-permissions.html[Config File Ownership and Permissions] -in the _Beats Platform Reference_ for more information. +for more information. +endif::[] + +For more information about configuring {beatname_uc}, also see: + +* <> +* {beats-ref}/config-file-format.html[Config file format] +ifeval::["{beatname_lc}"!="apm-server"] +* <<{beatname_lc}-reference-yml,+{beatname_lc}.reference.yml+>>: This reference configuration +file shows all non-deprecated options. You'll find it in the same location as ++{beatname_lc}.yml+. endif::[] diff --git a/libbeat/docs/shared-configuring.asciidoc b/libbeat/docs/shared/configuring-intro.asciidoc similarity index 51% rename from libbeat/docs/shared-configuring.asciidoc rename to libbeat/docs/shared/configuring-intro.asciidoc index 49ec5465144..e7be5e4f24c 100644 --- a/libbeat/docs/shared-configuring.asciidoc +++ b/libbeat/docs/shared/configuring-intro.asciidoc @@ -1,5 +1,7 @@ -To configure {beatname_uc}, you edit the configuration file. The default +TIP: To get started quickly, read <<{beatname_lc}-installation-configuration>>. + +To configure {beatname_uc}, edit the configuration file. The default configuration file is called +{beatname_lc}.yml+. The location of the file varies by platform. To locate the file, see <>. @@ -9,5 +11,7 @@ that shows all non-deprecated options. endif::[] TIP: See the -{beats-ref}/config-file-format.html[Config File Format] section of the -_Beats Platform Reference_ for more about the structure of the config file. +{beats-ref}/config-file-format.html[Config File Format] for more about the +structure of the config file. + +The following topics describe how to configure {beatname_uc}: diff --git a/libbeat/docs/shared/connecting-to-es.asciidoc b/libbeat/docs/shared/connecting-to-es.asciidoc new file mode 100644 index 00000000000..67cb2cc3755 --- /dev/null +++ b/libbeat/docs/shared/connecting-to-es.asciidoc @@ -0,0 +1,17 @@ +Connections to {es} and {kib} are required to set up {beatname_uc}. + +Set the connection information in +{beatname_lc}.yml+. To locate this +configuration file, see <>. + +include::{libbeat-dir}/tab-widgets/set-connection-widget.asciidoc[] + +To learn more about required roles and privileges, see +<>. + +ifeval::["{beatname_uc}"!="Winlogbeat"] +NOTE: You can send data to other <>, +ifndef::no-output-logstash[] +such as {ls}, +endif::no-output-logstash[] +but that requires additional configuration and setup. +endif::[] diff --git a/libbeat/docs/shared/obs-apps.asciidoc b/libbeat/docs/shared/obs-apps.asciidoc new file mode 100644 index 00000000000..9b5f7354ea0 --- /dev/null +++ b/libbeat/docs/shared/obs-apps.asciidoc @@ -0,0 +1,56 @@ +. Ingest data from other sources by installing and configuring other Elastic +{beats}: ++ +-- +[options="header"] +|=== +|Elastic {beats} | To capture + +ifeval::["{beatname_lc}"!="metricbeat"] +|{metricbeat-ref}/metricbeat-installation-configuration.html[{metricbeat}] +|Infrastructure metrics +endif::[] +ifeval::["{beatname_lc}"!="filebeat"] +|{filebeat-ref}/filebeat-installation-configuration.html[{filebeat}] +|Logs +endif::[] +ifeval::["{beatname_lc}"!="winlogbeat"] +|{winlogbeat-ref}/winlogbeat-installation-configuration.html[{winlogbeat}] +|Windows event logs +endif::[] +ifeval::["{beatname_lc}"!="heartbeat"] +|{heartbeat-ref}/heartbeat-installation-configuration.html[{heartbeat}] +|Uptime information +endif::[] +|{apm-overview-ref-v}/index.html[APM] +|Application performance metrics +ifeval::["{beatname_lc}"!="auditbeat"] +|{auditbeat-ref}/auditbeat-installation-configuration.html[{auditbeat}] +|Audit events +endif::[] +|=== +-- + +. Use the Observability apps in {kib} to search across all your data: ++ +-- +[options="header"] +|=== +|Elastic apps | Use to + +|{kibana-ref}/xpack-infra.html[{metrics-app}] +|Explore metrics about systems and services across your ecosystem + +|{kibana-ref}/xpack-logs.html[{logs-app}] +|Tail related log data in real time + +|{kibana-ref}/xpack-uptime.html[{uptime-app}] +|Monitor availability issues across your apps and services + +|{kibana-ref}/xpack-apm.html[APM app] +|Monitor application performance + +|{kibana-ref}/xpack-siem.html[{siem-app}] +|Analyze security events +|=== +-- diff --git a/libbeat/docs/shared/opendashboards.asciidoc b/libbeat/docs/shared/opendashboards.asciidoc new file mode 100644 index 00000000000..7e73fbc8f4b --- /dev/null +++ b/libbeat/docs/shared/opendashboards.asciidoc @@ -0,0 +1,28 @@ +// tag::open-dashboards-intro[] +{beatname_uc} comes with pre-built {kib} dashboards and UIs for visualizing log +data. You loaded the dashboards earlier when you ran the `setup` command. +// end::open-dashboards-intro[] + +// tag::open-dashboards[] +To open the dashboards: + +. Launch {kib}: ++ +-- +include::{libbeat-dir}/tab-widgets/open-kibana-widget.asciidoc[] +-- + +. In the side navigation, click *Discover*. To see {beatname_uc} data, make +sure the predefined +{beatname_lc}-*+ index pattern is selected. ++ +-- +TIP: If you don’t see data in {kib}, try changing the time filter to a larger +range. By default, {kib} shows the last 15 minutes. +-- + +. In the side navigation, click *Dashboard*, then select the dashboard that you +want to open. + +The dashboards are provided as examples. We recommend that you +{kibana-ref}/dashboard.html[customize] them to meet your needs. +// end::open-dashboards[] diff --git a/libbeat/docs/shared/redirects.asciidoc b/libbeat/docs/shared/redirects.asciidoc new file mode 100644 index 00000000000..dc9ca1d0d74 --- /dev/null +++ b/libbeat/docs/shared/redirects.asciidoc @@ -0,0 +1,34 @@ +["appendix",role="exclude",id="redirects"] += Deleted pages + +The following pages have moved or been deleted. + +[role="exclude",id="{beatname_lc}-configuration"] +=== Configure {beatname_uc} + +See <>. + +[role="exclude",id="{beatname_lc}-installation"] +=== Install {beatname_uc} + +See <<{beatname_lc}-installation-configuration>>. + +[role="exclude",id="view-kibana-dashboards"] +=== View the sample {kib} dashboards + +See <<{beatname_lc}-installation-configuration>>. + +[role="exclude",id="{beatname_lc}-getting-started"] +=== Get started with {beatname_uc} + +See <<{beatname_lc}-installation-configuration>>. + +ifeval::["{beatname_lc}"=="filebeat"] + +[role="exclude",id="{beatname_lc}-modules-quickstart"] +=== Quick start: modules for common log formats + +See <<{beatname_lc}-installation-configuration>>. + +//TODO: Remove any internal cross references that point to these IDs, set up +//redirects, then delete this file. diff --git a/libbeat/docs/shared/shutdown.asciidoc b/libbeat/docs/shared/shutdown.asciidoc new file mode 100644 index 00000000000..7ce26c34c17 --- /dev/null +++ b/libbeat/docs/shared/shutdown.asciidoc @@ -0,0 +1,13 @@ +[[shutdown]] +=== Stop {beatname_uc} + +An orderly shutdown of {beatname_uc} ensures that it has a chance to clean up +and close outstanding resources. You can help ensure an orderly shutdown by +stopping {beatname_uc} properly. + +If you’re running {beatname_uc} as a service, you can stop it via the service +management functionality provided by your installation. + +If you’re running {beatname_uc} directly in the console, you can stop it by +entering *Ctrl-C*. Alternatively, send SIGTERM to the {beatname_uc} process on a +POSIX system. diff --git a/libbeat/docs/shared/start-beat.asciidoc b/libbeat/docs/shared/start-beat.asciidoc new file mode 100644 index 00000000000..f0cabc42dec --- /dev/null +++ b/libbeat/docs/shared/start-beat.asciidoc @@ -0,0 +1,17 @@ +[id="{beatname_lc}-starting"] +=== Start {beatname_uc} + +Before starting {beatname_uc}: + +* Follow the steps in <<{beatname_lc}-installation-configuration>> to install, +configure, and set up the {beatname_uc} environment. +* Make sure {kib} and {es} are running. +* Make sure the user specified in +{beatname_lc}.yml+ is +<>. + +To start {beatname_uc}, run: + +include::{docdir}/getting-started.asciidoc[tag=start-step] + +// Add Javascript and CSS for tabbed panels +include::{libbeat-dir}/tab-widgets/code.asciidoc[] diff --git a/libbeat/docs/step-configure-credentials.asciidoc b/libbeat/docs/step-configure-credentials.asciidoc deleted file mode 100644 index 4fd3b62993d..00000000000 --- a/libbeat/docs/step-configure-credentials.asciidoc +++ /dev/null @@ -1,43 +0,0 @@ -. If {es} and {kib} are secured, set credentials in the +{beatname_lc}.yml+ config -file before you run the commands that set up and start {beatname_uc}. - -* If you're running our -https://www.elastic.co/cloud/elasticsearch-service[hosted {ess}] -on {ecloud}, specify your <> credentials. -For example: -+ -["source","yaml",subs="attributes"] ----------------------------------------------------------------------- -cloud.auth: "elastic:{pwd}" ----------------------------------------------------------------------- - -* If you're running {es} on your own hardware, specify your {es} and {kib} -credentials: -+ -["source","yaml",subs="attributes"] ----- -output.elasticsearch: - hosts: ["myEShost:9200"] - username: "filebeat_internal" - password: "{pwd}" <1> -setup.kibana: - host: "mykibanahost:5601" - username: "my_kibana_user" <2> <3> - password: "{pwd}" ----- -<1> This examples shows a hard-coded password, but you should store sensitive -values -ifndef::serverless[] -in the <>. -endif::[] -ifdef::serverless[] -in environment variables. -endif::[] -<2> The `username` and `password` settings for {kib} are optional. If you don't -specify credentials for {kib}, {beatname_uc} uses the `username` and `password` -specified for the {es} output. -<3> To use the pre-built Kibana dashboards, this user must have the -`kibana_user` {xpack-ref}/built-in-roles.html[built-in role] or equivalent -privileges. -+ -For more information, see <>. diff --git a/libbeat/docs/step-configure-kibana-endpoint.asciidoc b/libbeat/docs/step-configure-kibana-endpoint.asciidoc deleted file mode 100644 index 500b8077634..00000000000 --- a/libbeat/docs/step-configure-kibana-endpoint.asciidoc +++ /dev/null @@ -1,12 +0,0 @@ -. If you plan to use the sample {kib} dashboards provided with {beatname_uc}, -configure the {kib} endpoint. You can skip this step if {kib} is running on -the same host as {es}. -+ -[source,yaml] ----------------------------------------------------------------------- -setup.kibana: - host: "mykibanahost:5601" <1> ----------------------------------------------------------------------- -<1> The hostname and port of the machine where {kib} is running, -for example, `mykibanahost:5601`. If you specify a path after the port number, -include the scheme and port: `http://mykibanahost:5601/path`. diff --git a/libbeat/docs/step-configure-output.asciidoc b/libbeat/docs/step-configure-output.asciidoc deleted file mode 100644 index 838fd2d506b..00000000000 --- a/libbeat/docs/step-configure-output.asciidoc +++ /dev/null @@ -1,43 +0,0 @@ -ifndef::has_module_steps[] -ifndef::no-output-logstash[] -. Configure the output. {beatname_uc} supports a variety of -<>, but typically you'll either send events directly -to {es}, or to {ls} for additional processing. -+ -To send output directly to {es} (without using {ls}), set the location of the -{es} installation: -+ -endif::[] -ifdef::no-output-logstash[] -. Configure the {es} output by setting the location of the {es} installation: -+ -endif::[] -endif::has_module_steps[] -* If you're running our -https://www.elastic.co/cloud/elasticsearch-service[hosted {ess}] -on {ecloud}, specify your <>. For example: -+ -[source,yaml] ----------------------------------------------------------------------- -cloud.id: "staging:dXMtZWFzdC0xLmF3cy5mb3VuZC5pbyRjZWM2ZjI2MWE3NGJmMjRjZTMzYmI4ODExYjg0Mjk0ZiRjNmMyY2E2ZDA0MjI0OWFmMGNjN2Q3YTllOTYyNTc0Mw==" ----------------------------------------------------------------------- - -* If you're running {es} on your own hardware, set the host and port where -{beatname_uc} can find the {es} installation. For example: -+ -[source,yaml] ----------------------------------------------------------------------- -output.elasticsearch: - hosts: ["myEShost:9200"] ----------------------------------------------------------------------- -ifndef::has_module_steps[] -+ -ifndef::no-output-logstash[] -To send output to {ls}, -<> instead. For all other -outputs, see <>. -endif::[] -ifdef::no-output-logstash[] -For more information, see <>. -endif::[] -endif::has_module_steps[] diff --git a/libbeat/docs/step-look-at-config.asciidoc b/libbeat/docs/step-look-at-config.asciidoc deleted file mode 100644 index 4aaf01a1988..00000000000 --- a/libbeat/docs/step-look-at-config.asciidoc +++ /dev/null @@ -1,2 +0,0 @@ -For more information about configuring {beatname_uc}, see -<>. diff --git a/libbeat/docs/tab-widgets/code.asciidoc b/libbeat/docs/tab-widgets/code.asciidoc new file mode 100644 index 00000000000..61b18b0015d --- /dev/null +++ b/libbeat/docs/tab-widgets/code.asciidoc @@ -0,0 +1,166 @@ +// Defining styles and script here for simplicity. +++++ + + + +++++ diff --git a/libbeat/docs/tab-widgets/enable-modules-widget.asciidoc b/libbeat/docs/tab-widgets/enable-modules-widget.asciidoc new file mode 100644 index 00000000000..bc553b25085 --- /dev/null +++ b/libbeat/docs/tab-widgets/enable-modules-widget.asciidoc @@ -0,0 +1,112 @@ +++++ +
+
+ + + + + + +
+
+++++ + +include::enable-modules.asciidoc[tag=deb] + +++++ +
+ + + + + +
+++++ diff --git a/filebeat/docs/include/enable-modules-command.asciidoc b/libbeat/docs/tab-widgets/enable-modules.asciidoc similarity index 63% rename from filebeat/docs/include/enable-modules-command.asciidoc rename to libbeat/docs/tab-widgets/enable-modules.asciidoc index 4545e2e6e96..bd4345eed8c 100644 --- a/filebeat/docs/include/enable-modules-command.asciidoc +++ b/libbeat/docs/tab-widgets/enable-modules.asciidoc @@ -1,37 +1,41 @@ --- -*deb and rpm:* - +// tag::deb[] ["source","sh",subs="attributes"] ---- {beatname_lc} modules enable {modulename} ---- +// end::deb[] -*mac:* +// tag::rpm[] +["source","sh",subs="attributes"] +---- +{beatname_lc} modules enable {modulename} +---- +// end::rpm[] +// tag::mac[] ["source","sh",subs="attributes"] ---- ./{beatname_lc} modules enable {modulename} ---- +// end::mac[] -*brew:* - +// tag::brew[] ["source","sh",subs="attributes"] ---- {beatname_lc} modules enable {modulename} ---- +// end::brew[] -*linux:* - +// tag::linux[] ["source","sh",subs="attributes"] ---- ./{beatname_lc} modules enable {modulename} ---- +// end::linux[] -*win:* - +// tag::win[] ["source","sh",subs="attributes"] ---- PS > .{backslash}{beatname_lc}.exe modules enable {modulename} ---- - --- \ No newline at end of file +// end::win[] diff --git a/libbeat/docs/tab-widgets/install-deb-rpm-linux-widget.asciidoc b/libbeat/docs/tab-widgets/install-deb-rpm-linux-widget.asciidoc new file mode 100644 index 00000000000..d6186388bd5 --- /dev/null +++ b/libbeat/docs/tab-widgets/install-deb-rpm-linux-widget.asciidoc @@ -0,0 +1,58 @@ +++++ +
+
+ + + +
+
+++++ + +include::install.asciidoc[tag=deb] + +++++ +
+ + +
+++++ diff --git a/libbeat/docs/tab-widgets/install-linux-mac-win-short-widget.asciidoc b/libbeat/docs/tab-widgets/install-linux-mac-win-short-widget.asciidoc new file mode 100644 index 00000000000..f166aa5e45c --- /dev/null +++ b/libbeat/docs/tab-widgets/install-linux-mac-win-short-widget.asciidoc @@ -0,0 +1,58 @@ +++++ +
+
+ + + +
+
+++++ + +include::install.asciidoc[tag=mac] + +++++ +
+ + +
+++++ diff --git a/libbeat/docs/tab-widgets/install-widget.asciidoc b/libbeat/docs/tab-widgets/install-widget.asciidoc new file mode 100644 index 00000000000..c11df4b524d --- /dev/null +++ b/libbeat/docs/tab-widgets/install-widget.asciidoc @@ -0,0 +1,112 @@ +++++ +
+
+ + + + + + +
+
+++++ + +include::install.asciidoc[tag=deb] + +++++ +
+ + + + + +
+++++ diff --git a/libbeat/docs/tab-widgets/install.asciidoc b/libbeat/docs/tab-widgets/install.asciidoc new file mode 100644 index 00000000000..a866fc1d2da --- /dev/null +++ b/libbeat/docs/tab-widgets/install.asciidoc @@ -0,0 +1,146 @@ +// tag::deb[] +ifeval::["{release-state}"=="unreleased"] + +Version {version} of {beatname_uc} has not yet been released. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +["source","sh",subs="attributes"] +------------------------------------------------ +curl -L -O https://artifacts.elastic.co/downloads/beats/{beatname_lc}/{beatname_lc}-{version}-amd64.deb +sudo dpkg -i {beatname_lc}-{version}-amd64.deb +------------------------------------------------ + +endif::[] +// end::deb[] + +// tag::rpm[] +ifeval::["{release-state}"=="unreleased"] + +Version {version} of {beatname_uc} has not yet been released. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +["source","sh",subs="attributes"] +------------------------------------------------ +curl -L -O https://artifacts.elastic.co/downloads/beats/{beatname_lc}/{beatname_lc}-{version}-x86_64.rpm +sudo rpm -vi {beatname_lc}-{version}-x86_64.rpm +------------------------------------------------ + +endif::[] +// end::rpm[] + +// tag::mac[] +ifeval::["{release-state}"=="unreleased"] + +Version {version} of {beatname_uc} has not yet been released. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +["source","sh",subs="attributes"] +------------------------------------------------ +curl -L -O https://artifacts.elastic.co/downloads/beats/{beatname_lc}/{beatname_lc}-{version}-darwin-x86_64.tar.gz +tar xzvf {beatname_lc}-{version}-darwin-x86_64.tar.gz +------------------------------------------------ + +endif::[] +// end::mac[] + +// tag::brew[] +ifeval::["{release-state}"=="unreleased"] + +Version {version} of {beatname_uc} has not yet been released. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +["source","sh",subs="attributes"] +------------------------- +brew tap elastic/tap +brew install elastic/tap/{beatname_lc}-full +------------------------- + +This command installs the most recently released default distribution of +{beatname_uc}. To install the OSS distribution, specify ++elastic/tap/{beatname_lc}-oss+. + +endif::[] +// end::brew[] + +// tag::linux[] +ifeval::["{release-state}"=="unreleased"] + +Version {version} of {beatname_uc} has not yet been released. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +["source","sh",subs="attributes"] +------------------------------------------------ +curl -L -O https://artifacts.elastic.co/downloads/beats/{beatname_lc}/{beatname_lc}-{version}-linux-x86_64.tar.gz +tar xzvf {beatname_lc}-{version}-linux-x86_64.tar.gz +------------------------------------------------ + +endif::[] +// end::linux[] + +// tag::win[] +ifeval::["{release-state}"=="unreleased"] + +Version {version} of {beatname_uc} has not yet been released. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +. Download the {beatname_uc} Windows zip file from the +https://www.elastic.co/downloads/beats/{beatname_lc}[downloads page]. + +. Extract the contents of the zip file into `C:\Program Files`. + +. Rename the +{beatname_lc}--windows+ directory to +{beatname_uc}+. + +. Open a PowerShell prompt as an Administrator (right-click the PowerShell icon +and select *Run As Administrator*). + +. From the PowerShell prompt, run the following commands to install +{beatname_uc} as a Windows service: ++ +["source","sh",subs="attributes"] +---------------------------------------------------------------------- +PS > cd 'C:{backslash}Program Files{backslash}{beatname_uc}' +PS C:{backslash}Program Files{backslash}{beatname_uc}> .{backslash}install-service-{beatname_lc}.ps1 +---------------------------------------------------------------------- + +NOTE: If script execution is disabled on your system, you need to set the +execution policy for the current session to allow the script to run. For +example: ++PowerShell.exe -ExecutionPolicy UnRestricted -File .\install-service-{beatname_lc}.ps1+. + +endif::[] +// end::win[] + +// tag::win-short[] +ifeval::["{release-state}"=="unreleased"] + +Version {version} of {beatname_uc} has not yet been released. + +endif::[] + +ifeval::["{release-state}"!="unreleased"] + +. Download the {beatname_uc} Windows zip file from the +https://www.elastic.co/downloads/beats/{beatname_lc}[downloads page]. + +. Extract the contents of the zip file into `C:\Program Files`. + +endif::[] +// end::win-short[] diff --git a/libbeat/docs/tab-widgets/list-modules-widget.asciidoc b/libbeat/docs/tab-widgets/list-modules-widget.asciidoc new file mode 100644 index 00000000000..696c48889c5 --- /dev/null +++ b/libbeat/docs/tab-widgets/list-modules-widget.asciidoc @@ -0,0 +1,112 @@ +++++ +
+
+ + + + + + +
+
+++++ + +include::list-modules.asciidoc[tag=deb] + +++++ +
+ + + + + +
+++++ diff --git a/filebeat/docs/include/list-modules-command.asciidoc b/libbeat/docs/tab-widgets/list-modules.asciidoc similarity index 61% rename from filebeat/docs/include/list-modules-command.asciidoc rename to libbeat/docs/tab-widgets/list-modules.asciidoc index c79012325c7..ab1c883c58f 100644 --- a/filebeat/docs/include/list-modules-command.asciidoc +++ b/libbeat/docs/tab-widgets/list-modules.asciidoc @@ -1,36 +1,42 @@ --- -*deb and rpm:* - +// tag::deb[] ["source","sh",subs="attributes"] ---- {beatname_lc} modules list ---- +// end::deb[] -*mac:* +// tag::rpm[] +["source","sh",subs="attributes"] +---- +{beatname_lc} modules list +---- +// end::rpm[] +// tag::mac[] ["source","sh",subs="attributes"] ---- ./{beatname_lc} modules list ---- +// end::mac[] -*brew:* - +// tag::brew[] ["source","sh",subs="attributes"] ---- {beatname_lc} modules list ---- +// end::brew[] -*linux:* - +// tag::linux[] ["source","sh",subs="attributes"] ---- ./{beatname_lc} modules list ---- -*win:* +// end::linux[] +// tag::win[] ["source","sh",subs="attributes"] ---- PS > .{backslash}{beatname_lc}.exe modules list ---- --- +// end::win[] diff --git a/libbeat/docs/tab-widgets/open-kibana-widget.asciidoc b/libbeat/docs/tab-widgets/open-kibana-widget.asciidoc new file mode 100644 index 00000000000..849d2864fe8 --- /dev/null +++ b/libbeat/docs/tab-widgets/open-kibana-widget.asciidoc @@ -0,0 +1,40 @@ +++++ +
+
+ + +
+
+++++ + +include::open-kibana.asciidoc[tag=cloud] + +++++ +
+ +
+++++ diff --git a/libbeat/docs/tab-widgets/open-kibana.asciidoc b/libbeat/docs/tab-widgets/open-kibana.asciidoc new file mode 100644 index 00000000000..9adcde4ee0a --- /dev/null +++ b/libbeat/docs/tab-widgets/open-kibana.asciidoc @@ -0,0 +1,10 @@ +// tag::cloud[] +. https://cloud.elastic.co/[Log in] to your {ecloud} account. + +. Navigate to the {kib} endpoint in your deployment. +// end::cloud[] + +// tag::self-managed[] +Point your browser to http://localhost:5601[http://localhost:5601], replacing +`localhost` with the name of the {kib} host. +// end::self-managed[] diff --git a/libbeat/docs/tab-widgets/set-connection-widget.asciidoc b/libbeat/docs/tab-widgets/set-connection-widget.asciidoc new file mode 100644 index 00000000000..1365bab4588 --- /dev/null +++ b/libbeat/docs/tab-widgets/set-connection-widget.asciidoc @@ -0,0 +1,40 @@ +++++ +
+
+ + +
+
+++++ + +include::set-connection.asciidoc[tag=cloud] + +++++ +
+ +
+++++ diff --git a/libbeat/docs/tab-widgets/set-connection.asciidoc b/libbeat/docs/tab-widgets/set-connection.asciidoc new file mode 100644 index 00000000000..fe2e1c8a036 --- /dev/null +++ b/libbeat/docs/tab-widgets/set-connection.asciidoc @@ -0,0 +1,62 @@ +// tag::cloud[] + +Specify the <> of your {ess}, and set +<> to a user who is authorized to +set up {beatname_uc}. For example: + +["source","yaml",subs="attributes"] +---------------------------------------------------------------------- +cloud.id: "staging:dXMtZWFzdC0xLmF3cy5mb3VuZC5pbyRjZWM2ZjI2MWE3NGJmMjRjZTMzYmI4ODExYjg0Mjk0ZiRjNmMyY2E2ZDA0MjI0OWFmMGNjN2Q3YTllOTYyNTc0Mw==" +cloud.auth: "{beatname_lc}_setup:{pwd}" <1> +---------------------------------------------------------------------- +<1> This examples shows a hard-coded password, but you should store sensitive +values +ifndef::serverless[] +in the <>. +endif::[] +ifdef::serverless[] +in environment variables. +endif::[] +// end::cloud[] + +// tag::self-managed[] +. Set the host and port where {beatname_uc} can find the {es} installation, and +set the username and password of a user who is authorized to set up +{beatname_uc}. For example: ++ +["source","yaml",subs="attributes"] +---- +output.elasticsearch: + hosts: ["myEShost:9200"] + username: "{beatname_lc}_internal" + password: "{pwd}" <1> +---- +<1> This examples shows a hard-coded password, but you should store sensitive +values +ifndef::serverless[] +in the <>. +endif::[] +ifdef::serverless[] +in environment variables. +endif::[] + +. If you plan to use our pre-built {kib} dashboards, configure the {kib} +endpoint. Skip this step if {kib} is running on the same host as {es}. ++ +[source,yaml] +---------------------------------------------------------------------- + setup.kibana: + host: "mykibanahost:5601" <1> + username: "my_kibana_user" <2> <3> + password: "{pwd}" +---------------------------------------------------------------------- +<1> The hostname and port of the machine where {kib} is running, +for example, `mykibanahost:5601`. If you specify a path after the port number, +include the scheme and port: `http://mykibanahost:5601/path`. +<2> The `username` and `password` settings for {kib} are optional. If you don't +specify credentials for {kib}, {beatname_uc} uses the `username` and `password` +specified for the {es} output. +<3> To use the pre-built Kibana dashboards, this user must have the +`kibana_user` {ref}/built-in-roles.html[built-in role] or equivalent +privileges. +// end::self-managed[] diff --git a/libbeat/docs/tab-widgets/setup-deb-rpm-linux-widget.asciidoc b/libbeat/docs/tab-widgets/setup-deb-rpm-linux-widget.asciidoc new file mode 100644 index 00000000000..b0df100624e --- /dev/null +++ b/libbeat/docs/tab-widgets/setup-deb-rpm-linux-widget.asciidoc @@ -0,0 +1,58 @@ +++++ +
+
+ + + +
+
+++++ + +include::setup.asciidoc[tag=mac] + +++++ +
+ + +
+++++ diff --git a/libbeat/docs/tab-widgets/setup-linux-mac-win-widget.asciidoc b/libbeat/docs/tab-widgets/setup-linux-mac-win-widget.asciidoc new file mode 100644 index 00000000000..16d9061b121 --- /dev/null +++ b/libbeat/docs/tab-widgets/setup-linux-mac-win-widget.asciidoc @@ -0,0 +1,58 @@ +++++ +
+
+ + + +
+
+++++ + +include::setup.asciidoc[tag=mac] + +++++ +
+ + +
+++++ diff --git a/libbeat/docs/tab-widgets/setup-widget.asciidoc b/libbeat/docs/tab-widgets/setup-widget.asciidoc new file mode 100644 index 00000000000..b60f48aa7f3 --- /dev/null +++ b/libbeat/docs/tab-widgets/setup-widget.asciidoc @@ -0,0 +1,112 @@ +++++ +
+
+ + + + + + +
+
+++++ + +include::setup.asciidoc[tag=deb] + +++++ +
+ + + + + +
+++++ diff --git a/libbeat/docs/tab-widgets/setup.asciidoc b/libbeat/docs/tab-widgets/setup.asciidoc new file mode 100644 index 00000000000..d0e796d79f1 --- /dev/null +++ b/libbeat/docs/tab-widgets/setup.asciidoc @@ -0,0 +1,42 @@ +// tag::deb[] +["source","sh",subs="attributes"] +---- +{beatname_lc} setup -e +---- +// end::deb[] + +// tag::rpm[] +["source","sh",subs="attributes"] +---- +{beatname_lc} setup -e +---- +// end::rpm[] + +// tag::mac[] +["source","sh",subs="attributes"] +---- +./{beatname_lc} setup -e +---- +// end::mac[] + +// tag::brew[] +["source","sh",subs="attributes"] +---- +{beatname_lc} setup -e +---- +// end::brew[] + +// tag::linux[] +["source","sh",subs="attributes"] +---- +./{beatname_lc} setup -e +---- +// end::linux[] + +// tag::win[] +["source","sh",subs="attributes"] +---- +PS > .{backslash}{beatname_lc}.exe setup -e +---- +// end::win[] + diff --git a/libbeat/docs/tab-widgets/spinup-stack-widget.asciidoc b/libbeat/docs/tab-widgets/spinup-stack-widget.asciidoc new file mode 100644 index 00000000000..4b05b31976c --- /dev/null +++ b/libbeat/docs/tab-widgets/spinup-stack-widget.asciidoc @@ -0,0 +1,40 @@ +++++ +
+
+ + +
+
+++++ + +include::spinup-stack.asciidoc[tag=cloud] + +++++ +
+ +
+++++ diff --git a/libbeat/docs/tab-widgets/spinup-stack.asciidoc b/libbeat/docs/tab-widgets/spinup-stack.asciidoc new file mode 100644 index 00000000000..1ffc7663ac3 --- /dev/null +++ b/libbeat/docs/tab-widgets/spinup-stack.asciidoc @@ -0,0 +1,9 @@ +// tag::cloud[] +To get started quickly, spin up a deployment of our +https://www.elastic.co/cloud/elasticsearch-service[hosted {ess}]. The {ess} is +available on AWS, GCP, and Azure. {ess-trial}[Try it out for free]. +// end::cloud[] + +// tag::self-managed[] +See {stack-gs}/get-started-elastic-stack.html[Getting started with the {stack}]. +// end::self-managed[] diff --git a/libbeat/docs/tab-widgets/start-deb-rpm-linux-widget.asciidoc b/libbeat/docs/tab-widgets/start-deb-rpm-linux-widget.asciidoc new file mode 100644 index 00000000000..cc12343555e --- /dev/null +++ b/libbeat/docs/tab-widgets/start-deb-rpm-linux-widget.asciidoc @@ -0,0 +1,58 @@ +++++ +
+
+ + + +
+
+++++ + +include::start.asciidoc[tag=deb] + +++++ +
+ + +
+++++ diff --git a/libbeat/docs/tab-widgets/start-widget.asciidoc b/libbeat/docs/tab-widgets/start-widget.asciidoc new file mode 100644 index 00000000000..4551f970995 --- /dev/null +++ b/libbeat/docs/tab-widgets/start-widget.asciidoc @@ -0,0 +1,112 @@ +++++ +
+
+ + + + + + +
+
+++++ + +include::start.asciidoc[tag=deb] + +++++ +
+ + + + + +
+++++ diff --git a/libbeat/docs/tab-widgets/start.asciidoc b/libbeat/docs/tab-widgets/start.asciidoc new file mode 100644 index 00000000000..ce97a667a94 --- /dev/null +++ b/libbeat/docs/tab-widgets/start.asciidoc @@ -0,0 +1,148 @@ +// tag::deb[] +["source","sh",subs="attributes"] +---------------------------------------------------------------------- +sudo service {beatname_pkg} start +---------------------------------------------------------------------- + +// tag::initd-note[] +NOTE: If you use an `init.d` script to start {beatname_uc}, you can't specify command +line flags (see <>). To specify flags, start {beatname_uc} in +the foreground. + +// end::initd-note[] + +Also see <>. +// end::deb[] + +// tag::rpm[] +["source","sh",subs="attributes"] +---------------------------------------------------------------------- +sudo service {beatname_pkg} start +---------------------------------------------------------------------- + +include::start.asciidoc[tag=initd-note] + +Also see <>. + +// end::rpm[] + +// tag::mac[] +ifndef::has_modules_command[] +["source","sh",subs="attributes,callouts"] +---------------------------------------------------------------------- +sudo chown root {beatname_lc}.yml <1> +sudo ./{beatname_lc} -e +---------------------------------------------------------------------- +<1> You'll be running {beatname_uc} as root, so you need to change ownership +of the configuration file, or run {beatname_uc} with `--strict.perms=false` +specified. See +{beats-ref}/config-file-permissions.html[Config File Ownership and Permissions]. +endif::has_modules_command[] +ifdef::has_modules_command[] +["source","sh",subs="attributes,callouts"] +---------------------------------------------------------------------- +sudo chown root {beatname_lc}.yml <1> +sudo chown root modules.d/system.yml <1> +sudo ./{beatname_lc} -e +---------------------------------------------------------------------- +<1> You'll be running {beatname_uc} as root, so you need to change ownership of the +configuration file and any configurations enabled in the `modules.d` directory, +or run {beatname_uc} with `--strict.perms=false` specified. See +{beats-ref}/config-file-permissions.html[Config File Ownership and Permissions]. +endif::has_modules_command[] +// end::mac[] + +// tag::brew[] +To have launchd start +elastic/tap/{beatname_lc}+ and then restart it at login, +run: + +["source","sh",subs="attributes"] +----- +brew services start elastic/tap/{beatname_lc}-full +----- + +ifndef::requires-sudo[] +To run {beatname_uc} in the foreground instead of running it as a background +service, run: + +["source","sh",subs="attributes"] +----- +{beatname_lc} -e +----- +endif::[] + +ifdef::requires-sudo[] +To run {beatname_uc} in the foreground instead of running it as a background +service, run: + +ifndef::has_modules_command[] +["source","sh",subs="attributes"] +----- +sudo chown root /usr/local/etc/{beatname_lc}/{beatname_lc}.yml <1> +sudo {beatname_lc} -e +----- +<1> You'll be running {beatname_uc} as root, so you need to change ownership +of the configuration file, or run {beatname_uc} with `--strict.perms=false` +specified. See +{beats-ref}/config-file-permissions.html[Config File Ownership and Permissions]. +endif::has_modules_command[] + +ifdef::has_modules_command[] +["source","sh",subs="attributes,callouts"] +---------------------------------------------------------------------- +sudo chown root /usr/local/etc/{beatname_lc}/{beatname_lc}.yml <1> +sudo chown root /usr/local/etc/{beatname_lc}/modules.d/system.yml <1> +sudo {beatname_lc} -e +---------------------------------------------------------------------- +<1> You'll be running {beatname_uc} as root, so you need to change ownership of the +configuration file and any configurations enabled in the `modules.d` directory, +or run {beatname_uc} with `--strict.perms=false` specified. See +{beats-ref}/config-file-permissions.html[Config File Ownership and Permissions]. + +endif::has_modules_command[] + +endif::requires-sudo[] +// end::brew[] + +// tag::linux[] + +ifndef::has_modules_command[] +["source","sh",subs="attributes,callouts"] +---------------------------------------------------------------------- +sudo chown root {beatname_lc}.yml <1> +sudo ./{beatname_lc} -e +---------------------------------------------------------------------- +<1> You'll be running {beatname_uc} as root, so you need to change ownership +of the configuration file, or run {beatname_uc} with `--strict.perms=false` +specified. See +{beats-ref}/config-file-permissions.html[Config File Ownership and Permissions]. +endif::has_modules_command[] +ifdef::has_modules_command[] +["source","sh",subs="attributes,callouts"] +---------------------------------------------------------------------- +sudo chown root {beatname_lc}.yml <1> +sudo chown root modules.d/system.yml <1> +sudo ./{beatname_lc} -e +---------------------------------------------------------------------- +<1> You'll be running {beatname_uc} as root, so you need to change ownership of the +configuration file and any configurations enabled in the `modules.d` directory, +or run {beatname_uc} with `--strict.perms=false` specified. See +{beats-ref}/config-file-permissions.html[Config File Ownership and Permissions]. +endif::has_modules_command[] + +// end::linux[] + +// tag::win[] +["source","sh",subs="attributes"] +---------------------------------------------------------------------- +PS C:{backslash}Program Files{backslash}{beatname_lc}> Start-Service {beatname_lc} +---------------------------------------------------------------------- + +By default, Windows log files are stored in +C:{backslash}ProgramData{backslash}{beatname_lc}\Logs+. + +ifeval::["{beatname_lc}"=="metricbeat"] +NOTE: On Windows, statistics about system load and swap usage are currently +not captured +endif::[] + +// end::win[] diff --git a/libbeat/docs/template-config.asciidoc b/libbeat/docs/template-config.asciidoc index 52b602a6c28..3271d567c2a 100644 --- a/libbeat/docs/template-config.asciidoc +++ b/libbeat/docs/template-config.asciidoc @@ -15,8 +15,8 @@ connecting to Elasticsearch. ifndef::no-output-logstash[] NOTE: A connection to Elasticsearch is required to load the index template. If -the configured output is not Elasticsearch (or Elastic Cloud), you must <>. +the configured output is not Elasticsearch (or {ess}), you must +<>. endif::[] diff --git a/libbeat/docs/version.asciidoc b/libbeat/docs/version.asciidoc index 908d54baf6c..3fe60ddc83a 100644 --- a/libbeat/docs/version.asciidoc +++ b/libbeat/docs/version.asciidoc @@ -5,3 +5,4 @@ :python: 3.7 :docker: 1.12 :docker-compose: 1.11 +:libpcap: 0.8 diff --git a/libbeat/docs/visualizing-data.asciidoc b/libbeat/docs/visualizing-data.asciidoc deleted file mode 100644 index 71935d19f8d..00000000000 --- a/libbeat/docs/visualizing-data.asciidoc +++ /dev/null @@ -1,10 +0,0 @@ -[[visualizing-data]] -== Visualizing your data in Kibana - -This section describes how to load the sample Beats dashboards. After loading -the dashboards in Kibana, you can modify them to meet your needs. - -This section includes the following topics: - -* <> -* <> diff --git a/libbeat/outputs/logstash/docs/logstash.asciidoc b/libbeat/outputs/logstash/docs/logstash.asciidoc index 48f3790f3e0..e0cfdd0e4e0 100644 --- a/libbeat/outputs/logstash/docs/logstash.asciidoc +++ b/libbeat/outputs/logstash/docs/logstash.asciidoc @@ -47,20 +47,6 @@ some extra setup. For more information, see {logstash-ref}/filebeat-modules.html[Working with {beatname_uc} modules]. endif::[] -ifndef::win-only[] - -include::{libbeat-dir}/step-test-config.asciidoc[] - -endif::win-only[] - -ifdef::win-only[] - -TIP: To test your configuration file, change to the directory where the {beatname_uc} -binary is installed, and run {beatname_uc} in the foreground with the following -options specified: +.\winlogbeat.exe test config -c .\winlogbeat.yml -e+. - -endif::win-only[] - // end::shared-logstash-config[] ==== Accessing metadata fields diff --git a/metricbeat/README.md b/metricbeat/README.md index 5d817506b0a..206a7c10066 100644 --- a/metricbeat/README.md +++ b/metricbeat/README.md @@ -4,7 +4,7 @@ Metricbeat fetches a set of metrics on a predefined interval from the operating ## Getting started -Please follow the [getting started](https://www.elastic.co/guide/en/beats/metricbeat/current/metricbeat-getting-started.html) +Please follow the [getting started](https://www.elastic.co/guide/en/beats/metricbeat/current/metricbeat-installation-configuration.html) guide from the docs. ## Documentation diff --git a/metricbeat/docs/configuring-howto.asciidoc b/metricbeat/docs/configuring-howto.asciidoc index 91b6a7f120c..d379bb9e8f9 100644 --- a/metricbeat/docs/configuring-howto.asciidoc +++ b/metricbeat/docs/configuring-howto.asciidoc @@ -7,21 +7,7 @@ Configure ++++ -Before modifying configuration settings, make sure you've completed the -<> in the Getting Started. -This section describes some common use cases for changing configuration options. - -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+. -There's also a full example configuration file at -+/etc/{beatname_lc}/{beatname_lc}.reference.yml+ that shows all non-deprecated -options. For mac and win, look in the archive that you extracted. - -The {beatname_uc} configuration file uses http://yaml.org/[YAML] for its syntax. -See the {beats-ref}/config-file-format.html[Config File Format] section of the -_Beats Platform Reference_ for more about the structure of the config file. - -The following topics describe how to configure {beatname_uc}: +include::{libbeat-dir}/shared/configuring-intro.asciidoc[] * <> * <> diff --git a/metricbeat/docs/getting-started.asciidoc b/metricbeat/docs/getting-started.asciidoc new file mode 100644 index 00000000000..193af8783e7 --- /dev/null +++ b/metricbeat/docs/getting-started.asciidoc @@ -0,0 +1,166 @@ +:modulename: apache mysql + +[id="{beatname_lc}-installation-configuration"] +== {beatname_uc} quick start: installation and configuration + +++++ +Quick start: installation and configuration +++++ + +{beatname_uc} helps you monitor your servers and the services they host by +collecting metrics from the operating system and services. + +This guide describes how to get started quickly with metrics collection. +You'll learn how to: + +* install {beatname_uc} on each system you want to monitor +* specify the metrics you want to collect +* send the metrics to {es} +* visualize the metrics data in {kib} + +[role="screenshot"] +image::./images/{beatname_lc}-system-dashboard.png[{beatname_uc} System dashboard] + +[float] +=== Before you begin + +You need {es} for storing and searching your data, and {kib} for visualizing and +managing it. + +include::{libbeat-dir}/tab-widgets/spinup-stack-widget.asciidoc[] + +[float] +[[install]] +=== Step 1: Install {beatname_uc} + +Install {beatname_uc} as close as possible to the service you want to monitor. +For example, if you have four servers with MySQL running, it's recommended that +you run {beatname_uc} on each server. This allows {beatname_uc} to access your +service from localhost and does not cause any additional network traffic or +prevent {beatname_uc} from collecting metrics when there are network problems. +Metrics from multiple {beatname_uc} instances will be combined on the +Elasticsearch server. + +To download and install {beatname_uc}, use the commands that work with your +system: + +include::{libbeat-dir}/tab-widgets/install-widget.asciidoc[] + +[float] +[[other-installation-options]] +==== Other installation options + +* <> +* https://www.elastic.co/downloads/beats/{beatname_lc}[Download page] +* <> +* <> +* <> + +[float] +[[set-connection]] +=== Step 2: Connect to the {stack} + +include::{libbeat-dir}/shared/connecting-to-es.asciidoc[] + +[float] +[[enable-modules]] +=== Step 3: Enable and configure metrics collection modules + +{beatname_uc} uses modules to collect metrics. Each module defines the basic +logic for collecting data from a specific service, such as Redis or MySQL. A +module consists of metricsets that fetch and structure the data. Read +<> to learn more. + +. Identify the modules you need to enable. To see the list of available +<>, run: ++ +-- +include::{libbeat-dir}/tab-widgets/list-modules-widget.asciidoc[] +-- + +. From the installation directory, enable one or more modules. If you accept the +default configuration without enabling additional modules, {beatname_uc} +collects system metrics only. ++ +The following command enables the `apache` and `mysql` configs in the +`modules.d` directory: ++ +-- +include::{libbeat-dir}/tab-widgets/enable-modules-widget.asciidoc[] +-- ++ +See the <> to learn more about this command. If you are using a +Docker image, see <>. + +. In the module configs under `modules.d`, change the module settings to match +your environment. See <> for more about available +settings. + +include::{libbeat-dir}/shared/config-check.asciidoc[] + +[float] +[[setup-assets]] +=== Step 4: Set up assets + +{beatname_uc} comes with predefined assets for parsing, indexing, and +visualizing your data. To load these assets: + +. Make sure the user specified in +{beatname_lc}.yml+ is +<>. + +. From the installation directory, run: ++ +-- +include::{libbeat-dir}/tab-widgets/setup-widget.asciidoc[] +-- ++ +`-e` is optional and sends output to standard error instead of the configured log output. + +This step loads the recommended {ref}/indices-templates.html[index template] for writing to {es} +and deploys the sample dashboards for visualizing the data in {kib}. + +[TIP] +===== +A connection to {es} (or {ess}) is required to set up the initial +environment. If you're using a different output, such as {ls}, see +<> and <>. +===== + +[float] +[[start]] +=== Step 5: Start {beatname_uc} + +Before starting {beatname_uc}, modify the user credentials in ++{beatname_lc}.yml+ and specify a user who is +<>. + +To start {beatname_uc}, run: + +// tag::start-step[] +:requires-sudo: +include::{libbeat-dir}/tab-widgets/start-widget.asciidoc[] +:requires-sudo!: +// end::start-step[] + +{beatname_uc} should begin streaming metrics to {es}. + +[float] +[[view-data]] +=== Step 6: View your data in {kib} + +include::{libbeat-dir}/shared/opendashboards.asciidoc[tag=open-dashboards-intro] + +include::{libbeat-dir}/shared/opendashboards.asciidoc[tag=open-dashboards] + +[float] +=== What's next? + +Now that you have your infrastructure metrics streaming into {es}, learn how to +unify your logs, metrics, uptime, and application performance data. + +include::{libbeat-dir}/shared/obs-apps.asciidoc[] + +:modulename!: + +// Add Javascript and CSS for tabbed panels +include::{libbeat-dir}/tab-widgets/code.asciidoc[] diff --git a/metricbeat/docs/gettingstarted.asciidoc b/metricbeat/docs/gettingstarted.asciidoc deleted file mode 100644 index b32cd1280be..00000000000 --- a/metricbeat/docs/gettingstarted.asciidoc +++ /dev/null @@ -1,327 +0,0 @@ -[id="{beatname_lc}-getting-started"] -== Get started with {beatname_uc} - -++++ -Get started -++++ - -{beatname_uc} helps you monitor your servers and the services they host by -collecting metrics from the operating system and services. - -include::{libbeat-dir}/shared-getting-started-intro.asciidoc[] - -* <<{beatname_lc}-installation>> -* <<{beatname_lc}-configuration>> -* <<{beatname_lc}-template>> -* <> -* <<{beatname_lc}-starting>> -* <> -* <> - -[id="{beatname_lc}-installation"] -=== Step 1: Install {beatname_uc} - -You should install {beatname_uc} as close as possible to the service you want to -monitor. For example, if you have four servers with MySQL running, it's -recommended that you run {beatname_uc} on each server. This allows {beatname_uc} to -access your service from localhost and does not cause any additional network -traffic or prevent {beatname_uc} from collecting metrics when there are network -problems. Metrics from multiple {beatname_uc} instances will be combined on the -Elasticsearch server. - -include::{libbeat-dir}/shared-download-and-install.asciidoc[] - -[[deb]] -*deb:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes"] ------------------------------------------------- -curl -L -O https://artifacts.elastic.co/downloads/beats/{beatname_lc}/{beatname_lc}-{version}-amd64.deb -sudo dpkg -i {beatname_lc}-{version}-amd64.deb ------------------------------------------------- - -endif::[] - -[[rpm]] -*rpm:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes"] ------------------------------------------------- -curl -L -O https://artifacts.elastic.co/downloads/beats/{beatname_lc}/{beatname_lc}-{version}-x86_64.rpm -sudo rpm -vi {beatname_lc}-{version}-x86_64.rpm ------------------------------------------------- - -endif::[] - -[[mac]] -*mac:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes"] ------------------------------------------------- -curl -L -O https://artifacts.elastic.co/downloads/beats/{beatname_lc}/{beatname_lc}-{version}-darwin-x86_64.tar.gz -tar xzvf {beatname_lc}-{version}-darwin-x86_64.tar.gz ------------------------------------------------- - -endif::[] - -include::{libbeat-dir}/shared-brew-install.asciidoc[] - -[[linux]] -*linux:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes"] ------------------------------------------------- -curl -L -O https://artifacts.elastic.co/downloads/beats/{beatname_lc}/{beatname_lc}-{version}-linux-x86_64.tar.gz -tar xzvf {beatname_lc}-{version}-linux-x86_64.tar.gz ------------------------------------------------- - -endif::[] - -[[docker]] -*docker:* - -See <> for deploying Docker containers. - -[[kubernetes]] -*kubernetes:* - -See <> for deploying with Kubernetes. - -[[cloudfoundry]] -*cloudfoundry:* - -See <> for deploying with Cloud Foundry. - -[[win]] -*win:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -. Download the {beatname_uc} Windows zip file from the -https://www.elastic.co/downloads/beats/{beatname_lc}[downloads page]. - -. Extract the contents of the zip file into `C:\Program Files`. - -. Rename the +{beatname_lc}--windows+` directory to +{beatname_uc}+. - -. Open a PowerShell prompt as an Administrator (right-click the PowerShell icon -and select *Run As Administrator*). - -. From the PowerShell prompt, run the following commands to install {beatname_uc} -as a Windows service: -+ -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -PS > cd 'C:{backslash}Program Files{backslash}{beatname_uc}' -PS C:{backslash}Program Files{backslash}{beatname_uc}> .{backslash}install-service-{beatname_lc}.ps1 ----------------------------------------------------------------------- - -NOTE: If script execution is disabled on your system, you need to set the -execution policy for the current session to allow the script to run. For -example: +PowerShell.exe -ExecutionPolicy UnRestricted -File -.{backslash}install-service-{beatname_lc}.ps1+. - -endif::[] - -Before starting {beatname_uc}, you should look at the configuration options in the -configuration file, for example +C:{backslash}Program Files{backslash}{beatname_uc}{backslash}{beatname_lc}.yml+. -For more information about these options, see -<>. - -[id="{beatname_lc}-configuration"] -=== Step 2: Configure {beatname_uc} - -include::{libbeat-dir}/shared-configuring.asciidoc[] - -When you configure {beatname_uc}, you need to specify which -<<{beatname_lc}-modules,modules>> to run. {beatname_uc} uses modules to collect -metrics. Each module defines the basic logic for collecting data from a specific -service, such as Redis or MySQL. A module consists of metricsets that fetch and -structure the data. Read <> to learn more. - -To configure {beatname_uc}: - -. Enable the modules that you want to run. If you accept the default -configuration without enabling additional modules, {beatname_uc} collects system -metrics only. -+ -You can either enable the default module configurations defined in the -`modules.d` directory (recommended), or add the module configs to the -+{beatname_lc}.yml+ file. The `modules.d` directory contains default -configurations for all available {beatname_uc} modules. -+ -If you are using a Docker image, see <>. -+ -The following examples enable the `apache` and `mysql` configs in the -`modules.d` directory: -+ -*deb and rpm:* -+ -["source","sh",subs="attributes"] ----- -{beatname_lc} modules enable apache mysql ----- -+ -*mac and linux:* -+ -["source","sh",subs="attributes"] ----- -./{beatname_lc} modules enable apache mysql ----- -+ -*win:* -+ -["source","sh",subs="attributes"] ----- -PS > .{backslash}{beatname_lc}.exe modules enable apache mysql ----- -+ -See the <> to learn more about this command. -+ -To change the default module configurations, modify the `.yml` files in the -`modules.d` directory. See <> for more about available -settings. -+ -See <> if you want to add the module configs to the -+{beatname_lc}.yml+ file rather than using the `modules.d` directory. - -include::{libbeat-dir}/step-configure-output.asciidoc[] - -include::{libbeat-dir}/step-configure-kibana-endpoint.asciidoc[] - -include::{libbeat-dir}/step-configure-credentials.asciidoc[] - -include::{libbeat-dir}/step-test-config.asciidoc[] - -include::{libbeat-dir}/step-look-at-config.asciidoc[] - -[id="{beatname_lc}-template"] -=== Step 3: Load the index template in Elasticsearch - -include::{libbeat-dir}/shared-template-load.asciidoc[] - -[[load-kibana-dashboards]] -=== Step 4: Set up the Kibana dashboards - -include::{libbeat-dir}/dashboards.asciidoc[] - -[id="{beatname_lc}-starting"] -=== Step 5: Start {beatname_uc} - -Run {beatname_uc} by issuing the appropriate command for your platform. If you -are accessing a secured Elasticsearch cluster, make sure you've configured -credentials as described in <<{beatname_lc}-configuration>>. - -NOTE: If you use an init.d script to start {beatname_uc} on deb or rpm, you can't -specify command line flags (see <>). To specify flags, -start {beatname_uc} in the foreground. - -*deb and rpm:* - -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -sudo service {beatname_lc} start ----------------------------------------------------------------------- - -*docker:* - -See <>. - -*mac and linux:* - -["source","sh",subs="attributes,callouts"] ----------------------------------------------------------------------- -sudo chown root {beatname_lc}.yml <1> -sudo chown root modules.d/system.yml <1> -sudo ./{beatname_lc} -e ----------------------------------------------------------------------- -<1> You'll be running {beatname_uc} as root, so you need to change ownership of the -configuration file and any configurations enabled in the `modules.d` directory, -or run {beatname_uc} with `--strict.perms=false` specified. See -{beats-ref}/config-file-permissions.html[Config File Ownership and Permissions] -in the _Beats Platform Reference_. - -:requires-sudo: -include::{libbeat-dir}/shared-brew-run.asciidoc[] -:requires-sudo!: - -*win:* - -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -PS C:{backslash}Program Files{backslash}{beatname_uc}> Start-Service {beatname_lc} ----------------------------------------------------------------------- - -By default the log files are stored in +C:{backslash}ProgramData{backslash}{beatname_lc}{backslash}Logs+. - -NOTE: On Windows, statistics about system load and swap usage are currently -not captured. - -==== Test the {beatname_uc} installation - -To verify that your server's statistics are present in Elasticsearch, issue -the following command: - -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -curl -XGET 'http://localhost:9200/{beatname_lc}-*/_search?pretty' ----------------------------------------------------------------------- - -Make sure that you replace `localhost:9200` with the address of your -Elasticsearch instance. - -On Windows, if you don't have cURL installed, simply point your browser to the -URL. - -[[view-kibana-dashboards]] -=== Step 6: View the sample Kibana dashboards - -To make it easier for you to start monitoring your servers in Kibana, -we have created example {beatname_uc} dashboards. You loaded the dashboards -earlier when you ran the `setup` command. - -include::{libbeat-dir}/opendashboards.asciidoc[] - -The dashboards are provided as examples. We recommend that you -{kibana-ref}/dashboard.html[customize] them to meet your needs. - -[role="screenshot"] -image::./images/{beatname_lc}_system_dashboard.png[{beatname_uc} Dashboard] diff --git a/metricbeat/docs/howto/howto.asciidoc b/metricbeat/docs/howto/howto.asciidoc index 54eef117163..302af5435e9 100644 --- a/metricbeat/docs/howto/howto.asciidoc +++ b/metricbeat/docs/howto/howto.asciidoc @@ -5,6 +5,9 @@ -- Learn how to perform common {beatname_uc} configuration tasks. +* <<{beatname_lc}-template>> +* <> +* <> * <<{beatname_lc}-geoip>> * <> * <> @@ -13,6 +16,12 @@ Learn how to perform common {beatname_uc} configuration tasks. -- +include::{libbeat-dir}/howto/load-index-templates.asciidoc[] + +include::{libbeat-dir}/howto/change-index-name.asciidoc[] + +include::{libbeat-dir}/howto/load-dashboards.asciidoc[] + include::{libbeat-dir}/shared-geoip.asciidoc[] :standalone: diff --git a/metricbeat/docs/images/kibana-created-indexes.png b/metricbeat/docs/images/kibana-created-indexes.png deleted file mode 100644 index ad9c65ae1c7..00000000000 Binary files a/metricbeat/docs/images/kibana-created-indexes.png and /dev/null differ diff --git a/metricbeat/docs/images/kibana-navigation-vis.png b/metricbeat/docs/images/kibana-navigation-vis.png deleted file mode 100644 index a8c0e62ed57..00000000000 Binary files a/metricbeat/docs/images/kibana-navigation-vis.png and /dev/null differ diff --git a/metricbeat/docs/images/metricbeat-system-dashboard.png b/metricbeat/docs/images/metricbeat-system-dashboard.png new file mode 100644 index 00000000000..648023f1238 Binary files /dev/null and b/metricbeat/docs/images/metricbeat-system-dashboard.png differ diff --git a/metricbeat/docs/index.asciidoc b/metricbeat/docs/index.asciidoc index 656b8171ae6..fc3972a4b21 100644 --- a/metricbeat/docs/index.asciidoc +++ b/metricbeat/docs/index.asciidoc @@ -37,9 +37,7 @@ include::{libbeat-dir}/shared-beats-attributes.asciidoc[] include::./overview.asciidoc[] -include::./gettingstarted.asciidoc[] - -include::{libbeat-dir}/repositories.asciidoc[] +include::./getting-started.asciidoc[] include::./setting-up-running.asciidoc[] @@ -66,3 +64,5 @@ include::./troubleshooting.asciidoc[] include::./faq.asciidoc[] include::{libbeat-dir}/contributing-to-beats.asciidoc[] + +include::{libbeat-dir}/shared/redirects.asciidoc[] diff --git a/metricbeat/docs/metricbeat-options.asciidoc b/metricbeat/docs/metricbeat-options.asciidoc index 0d3e5f99afd..84e13274f44 100644 --- a/metricbeat/docs/metricbeat-options.asciidoc +++ b/metricbeat/docs/metricbeat-options.asciidoc @@ -1,3 +1,5 @@ +:modulename: apache mysql + [[configuration-metricbeat]] == Configure modules @@ -5,29 +7,25 @@ Modules ++++ -Metricbeat provides a couple different ways to enable modules and metricsets: +You can configure modules in the `modules.d` directory (recommended), or in the +{beatname_uc} configuration file. -* <> -* <> +Before running {beatname_uc} with modules enabled, make sure you also set up the +environment to use {kib} dashboards. See +<<{beatname_lc}-installation-configuration>> for more information. include::{libbeat-dir}/shared-note-file-permissions.asciidoc[] [float] -[[enable-modules-d-configs]] -=== Enable module configs in the `modules.d` directory +[[configure-modules-d-configs]] +=== Configure modules in the `modules.d` directory The `modules.d` directory contains default configurations for all the modules -available in Metricbeat. You can enable or disable specific module -configurations under `modules.d` by running the <> commands. - -For example, to enable the `apache` and `mysql` configs in the `modules.d` -directory, you use: +available in {beatname_uc}. To enable or disable specific module configurations +under `modules.d`, run the +<> command. For example: -[source,shell] ----- -./metricbeat modules enable apache mysql ----- +include::{libbeat-dir}/tab-widgets/enable-modules-widget.asciidoc[] Then when you run Metricbeat, it loads the corresponding module configurations specified in the `modules.d` directory (for example, `modules.d/apache.yml` and @@ -35,12 +33,9 @@ specified in the `modules.d` directory (for example, `modules.d/apache.yml` and To see a list of enabled and disabled modules, run: -[source,shell] ----- -./metricbeat modules list ----- +include::{libbeat-dir}/tab-widgets/list-modules-widget.asciidoc[] -You can change the default module configurations by modifying the `.yml` files +To change the default module configurations, modify the `.yml` files in the `modules.d` directory. The following example shows a basic configuration for the Apache module: @@ -62,25 +57,25 @@ The following example shows a basic configuration for the Apache module: See <> for additional configuration examples. [float] -[[enable-modules-config-file]] -=== Enable module configs in the +{beatname_lc}.yml+ file +[[configure-modules-config-file]] +=== Configure modules in the +{beatname_lc}.yml+ file When possible, you should use the config files in the `modules.d` directory. -However, enabling modules directly in the config file is a practical approach if -you have upgraded from a previous version of {beatname_uc} and don't want to -move your module configs to the `modules.d` directory. You can continue to -configure modules in the +{beatname_lc}.yml+ file, but you won't be able to use -the `modules` command to enable and disable configurations because the command -requires the `modules.d` layout. +However, configuring <<{beatname_lc}-modules,modules>> directly in the config +file is a practical approach if you have upgraded from a previous version +of {beatname_uc} and don't want to move your module configs to the `modules.d` +directory. You can continue to configure modules in the +{beatname_lc}.yml+ +file, but you won't be able to use the `modules` command to enable and disable +configurations because the command requires the `modules.d` layout. To enable specific modules and metricsets in the +{beatname_lc}.yml+ config -file, you can add entries to the +{beatname_lc}.modules+ list. Each entry in the +file, add entries to the +{beatname_lc}.modules+ list. Each entry in the list begins with a dash (-) and is followed by settings for that module. -The following example shows a configuration where the apache and mysql modules -are enabled: +The following example shows a configuration where the `apache` and `mysql` +modules are enabled: [source,yaml] ------------------------------------------------------------------------------ @@ -318,3 +313,7 @@ query: - 2.95 - -15 ---- +:modulename!: + +// Add Javascript and CSS for tabbed panels +include::{libbeat-dir}/tab-widgets/code.asciidoc[] \ No newline at end of file diff --git a/metricbeat/docs/overview.asciidoc b/metricbeat/docs/overview.asciidoc index 95cf3c7789c..22cfde9c7ea 100644 --- a/metricbeat/docs/overview.asciidoc +++ b/metricbeat/docs/overview.asciidoc @@ -1,10 +1,6 @@ [[metricbeat-overview]] == Metricbeat overview -++++ -Overview -++++ - Metricbeat is a lightweight shipper that you can install on your servers to periodically collect metrics from the operating system and from services running on the server. Metricbeat takes the metrics and statistics that it collects and diff --git a/metricbeat/docs/reload-configuration.asciidoc b/metricbeat/docs/reload-configuration.asciidoc index 2c467a823cf..5fd45635866 100644 --- a/metricbeat/docs/reload-configuration.asciidoc +++ b/metricbeat/docs/reload-configuration.asciidoc @@ -9,7 +9,7 @@ Metricbeat can load external configuration files for modules, which allows you to separate your configuration into multiple smaller configuration files. To use this, you specify the `path` option under `metricbeat.config.modules` in the main `metricbeat.yml` configuration file. By default, Metricbeat loads the -module configurations enabled in the <> +module configurations enabled in the <> directory. For example: [source,yaml] diff --git a/metricbeat/docs/setting-up-running.asciidoc b/metricbeat/docs/setting-up-running.asciidoc index 002cd8bd4b1..1139731e201 100644 --- a/metricbeat/docs/setting-up-running.asciidoc +++ b/metricbeat/docs/setting-up-running.asciidoc @@ -11,15 +11,17 @@ Set up and run ++++ -Before reading this section, see the -<<{beatname_lc}-getting-started,getting started documentation>> for basic +Before reading this section, see +<<{beatname_lc}-installation-configuration>> for basic installation instructions to get you started. -This section includes additional information on how to set up and run +This section includes additional information on how to install, set up, and run {beatname_uc}, including: * <> +* <> + * <> * <> @@ -30,6 +32,10 @@ This section includes additional information on how to set up and run * <> +* <<{beatname_lc}-starting>> + +* <> + //MAINTAINERS: If you add a new file to this section, make sure you update the bulleted list ^^ too. include::{libbeat-dir}/shared-directory-layout.asciidoc[] @@ -38,6 +44,8 @@ include::{libbeat-dir}/keystore.asciidoc[] include::{libbeat-dir}/command-reference.asciidoc[] +include::{libbeat-dir}/repositories.asciidoc[] + include::./running-on-docker.asciidoc[] include::./running-on-kubernetes.asciidoc[] @@ -46,4 +54,6 @@ include::./running-on-cloudfoundry.asciidoc[] include::{libbeat-dir}/shared-systemd.asciidoc[] -include::{libbeat-dir}/shared-shutdown.asciidoc[] +include::{libbeat-dir}/shared/start-beat.asciidoc[] + +include::{libbeat-dir}/shared/shutdown.asciidoc[] diff --git a/metricbeat/docs/upgrading.asciidoc b/metricbeat/docs/upgrading.asciidoc index 5a01b443ae8..47652390843 100644 --- a/metricbeat/docs/upgrading.asciidoc +++ b/metricbeat/docs/upgrading.asciidoc @@ -1,7 +1,7 @@ [[upgrading-metricbeat]] == Upgrade Metricbeat -For information about upgrading to a new version, see the following topics in the _Beats Platform Reference_: +For information about upgrading to a new version, see: * {beats-ref}/breaking-changes.html[Breaking Changes] * {beats-ref}/upgrading.html[Upgrade] diff --git a/packetbeat/README.md b/packetbeat/README.md index 832e79065c1..fb164d1dc49 100644 --- a/packetbeat/README.md +++ b/packetbeat/README.md @@ -17,7 +17,7 @@ To learn more about Packetbeat, check out Configure ++++ -Before modifying configuration settings, make sure you've completed the -<> in the Getting Started. -This section describes some common use cases for changing configuration options. - -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+. -There's also a full example configuration file at -+/etc/{beatname_lc}/{beatname_lc}.reference.yml+ that shows all non-deprecated -options. For mac and win, look in the archive that you extracted. - -The {beatname_uc} configuration file uses http://yaml.org/[YAML] for its syntax. -See the {beats-ref}/config-file-format.html[Config File Format] section of the -_Beats Platform Reference_ for more about the structure of the config file. - -The following topics describe how to configure Packetbeat: +include::{libbeat-dir}/shared/configuring-intro.asciidoc[] * <> * <> diff --git a/packetbeat/docs/getting-started.asciidoc b/packetbeat/docs/getting-started.asciidoc new file mode 100644 index 00000000000..2ba458c9737 --- /dev/null +++ b/packetbeat/docs/getting-started.asciidoc @@ -0,0 +1,217 @@ +[id="{beatname_lc}-installation-configuration"] +== {beatname_uc} quick start: installation and configuration + +++++ +Quick start: installation and configuration +++++ + +The best way to understand the value of a network packet analytics system like +{beatname_uc} is to try it on your own traffic. + +This guide describes how to get started quickly with network packets analytics. +You'll learn how to: + +* install {beatname_uc} on each system you want to monitor +* specify the network devices and protocols to sniff +* parse the packet data into fields and send it to {es} +* visualize the packet data in {kib} + +[role="screenshot"] +image::./images/packetbeat-overview-dashboard.png[{beatname_uc} Overview dashboard] + +[float] +=== Before you begin + +* You need {es} for storing and searching your data, and {kib} for visualizing +and managing it. ++ +-- +include::{libbeat-dir}/tab-widgets/spinup-stack-widget.asciidoc[] +-- + +* On most platforms, {beatname_uc} requires the libpcap packet capture +library. Depending on your OS, you might need to install it: ++ +-- +include::tab-widgets/install-libpcap-widget.asciidoc[] +-- + +[float] +[[installation]] +=== Step 1: Install {beatname_uc} + +You can install {beatname_uc} on dedicated servers, getting the traffic from +mirror ports or tap devices, or you can install it on your existing application +servers. + +To download and install {beatname_uc}, use the commands that work with your +system: + +include::{libbeat-dir}/tab-widgets/install-widget.asciidoc[] + +[float] +[[other-installation-options]] +==== Other installation options + +* <> +* https://www.elastic.co/downloads/beats/{beatname_lc}[Download page] +* <> + +[float] +[[set-connection]] +=== Step 2: Connect to the {stack} + +include::{libbeat-dir}/shared/connecting-to-es.asciidoc[] + + +[float] +[[configuration]] +=== Step 3: Configure sniffing + +In +{beatname_lc}.yml+, configure the network devices and protocols to +capture traffic from. + +. Set the sniffer type. By default, {beatname_uc} uses `pcap`, which uses the +libpcap library and works on most platforms. ++ +On Linux, set the sniffer type to `af_packet` to use memory-mapped sniffing. +This option is faster than libpcap and doesn’t require a kernel module, but +it’s Linux-specific: ++ +[source,yaml] +---- +packetbeat.interfaces.type: af_packet +---- + +. Specify the network device to capture traffic from. For example: ++ +[source,yaml] +---- +packetbeat.interfaces.device: eth0 +---- ++ +[TIP] +==== +On Linux, specify `packetbeat.interfaces.device: any` to capture all +messages sent or received by the server where {beatname_uc} is installed. +The `any` setting does not work on macOS. +==== ++ +To see a list of available devices, run: ++ +-- +include::tab-widgets/devices-widget.asciidoc[] +-- ++ +For more information about these settings, see <>. + +. In the `protocols` section, configure the ports where {beatname_uc} can find +each protocol. If you use any non-standard ports, add them here. Otherwise, +use the default values. ++ +[source,yaml] +---------------------------------------------------------------------- +packetbeat.protocols: + +- type: dhcpv4 + ports: [67, 68] + +- type: dns + ports: [53] + +- type: http + ports: [80, 8080, 8081, 5000, 8002] + +- type: memcache + ports: [11211] + +- type: mysql + ports: [3306,3307] + +- type: pgsql + ports: [5432] + +- type: redis + ports: [6379] + +- type: thrift + ports: [9090] + +- type: mongodb + ports: [27017] + +- type: cassandra + ports: [9042] + +- type: tls + ports: [443, 993, 995, 5223, 8443, 8883, 9243] + +---------------------------------------------------------------------- + +include::{libbeat-dir}/shared/config-check.asciidoc[] + +[float] +[[setup-assets]] +=== Step 4: Set up assets + +{beatname_uc} comes with predefined assets for parsing, indexing, and +visualizing your data. To load these assets: + +. Make sure the user specified in +{beatname_lc}.yml+ is +<>. + +. From the installation directory, run: ++ +-- +include::{libbeat-dir}/tab-widgets/setup-widget.asciidoc[] +-- ++ +`-e` is optional and sends output to standard error instead of the configured log output. + +This step loads the recommended {ref}/indices-templates.html[index template] for writing to {es} +and deploys the sample dashboards for visualizing the data in {kib}. + +[TIP] +===== +A connection to {es} (or {ess}) is required to set up the initial +environment. If you're using a different output, such as {ls}, see +<> and <>. +===== + +[float] +[[start]] +=== Step 5: Start {beatname_uc} + +Before starting {beatname_uc}, modify the user credentials in ++{beatname_lc}.yml+ and specify a user who is +<>. + +To start {beatname_uc}, run: + +// tag::start-step[] +include::{libbeat-dir}/tab-widgets/start-widget.asciidoc[] +// end::start-step[] + +{beatname_uc} should begin streaming data to {es}. + +[float] +[[view-data]] +=== Step 6: View your data in {kib} + +include::{libbeat-dir}/shared/opendashboards.asciidoc[tag=open-dashboards-intro] + +include::{libbeat-dir}/shared/opendashboards.asciidoc[tag=open-dashboards] + +TIP: To populate the client locations map in the overview dashboard, follow the +steps described in <<{beatname_lc}-geoip>>. + +[float] +=== What's next? + +Now that you have your data streaming into {es}, learn how to unify your logs, +metrics, uptime, and application performance data. + +include::{libbeat-dir}/shared/obs-apps.asciidoc[] + +// Add Javascript and CSS for tabbed panels +include::{libbeat-dir}/tab-widgets/code.asciidoc[] diff --git a/packetbeat/docs/gettingstarted.asciidoc b/packetbeat/docs/gettingstarted.asciidoc deleted file mode 100644 index 1c27b08e62e..00000000000 --- a/packetbeat/docs/gettingstarted.asciidoc +++ /dev/null @@ -1,341 +0,0 @@ -[[packetbeat-getting-started]] -== Get started with {beatname_uc} - -++++ -Get started -++++ - -The best way to understand the value of a network packet analytics system like -Packetbeat is to try it on your own traffic. - -include::{libbeat-dir}/shared-getting-started-intro.asciidoc[] - -* <> -* <> -* <> -* <> -* <> -* <> -* <> - -[[packetbeat-installation]] -=== Step 1: Install Packetbeat - -include::{libbeat-dir}/shared-download-and-install.asciidoc[] - -[[deb]] -*deb:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes,callouts"] ----------------------------------------------------------------------- -sudo apt-get install libpcap0.8 -curl -L -O https://artifacts.elastic.co/downloads/beats/packetbeat/packetbeat-{version}-amd64.deb -sudo dpkg -i packetbeat-{version}-amd64.deb ----------------------------------------------------------------------- - -endif::[] - -[[rpm]] -*rpm:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes,callouts"] ----------------------------------------------------------------------- -sudo yum install libpcap -curl -L -O https://artifacts.elastic.co/downloads/beats/packetbeat/packetbeat-{version}-x86_64.rpm -sudo rpm -vi packetbeat-{version}-x86_64.rpm ----------------------------------------------------------------------- - -endif::[] - -[[docker]] -*docker:* - -See <> for deploying Docker containers. - -[[mac]] -*mac:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes,callouts"] ----------------------------------------------------------------------- -curl -L -O https://artifacts.elastic.co/downloads/beats/packetbeat/packetbeat-{version}-darwin-x86_64.tar.gz -tar xzvf packetbeat-{version}-darwin-x86_64.tar.gz ----------------------------------------------------------------------- - -endif::[] - -include::{libbeat-dir}/shared-brew-install.asciidoc[] - -[[linux]] -*linux:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes,callouts"] ----------------------------------------------------------------------- -curl -L -O https://artifacts.elastic.co/downloads/beats/packetbeat/packetbeat-{version}-linux-x86_64.tar.gz -tar xzvf packetbeat-{version}-linux-x86_64.tar.gz ----------------------------------------------------------------------- - -endif::[] - -[[win]] -*win:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -. Download and install a packet sniffing library, -such as https://nmap.org/npcap/[Npcap], that implements the -https://github.com/the-tcpdump-group/libpcap[libpcap] interfaces. -+ -If you use Npcap, make sure you install it in WinPcap API-compatible mode. If -you plan to capture traffic from the loopback device (127.0.0.1 traffic), also -select the option to support loopback traffic. - -. Download the Packetbeat Windows zip file from the -https://www.elastic.co/downloads/beats/packetbeat[downloads page]. - -. Extract the contents of the zip file into `C:\Program Files`. - -. Rename the `packetbeat--windows` directory to `Packetbeat`. - -. Open a PowerShell prompt as an Administrator (right-click the PowerShell icon and select *Run As Administrator*). - -. From the PowerShell prompt, run the following commands to install Packetbeat as a Windows service: -+ -[source,shell] ----------------------------------------------------------------------- -PS > cd 'C:\Program Files\Packetbeat' -PS C:\Program Files\Packetbeat> .\install-service-packetbeat.ps1 ----------------------------------------------------------------------- - -NOTE: If script execution is disabled on your system, you need to set the execution policy for the current session to allow the script to run. For example: `PowerShell.exe -ExecutionPolicy UnRestricted -File .\install-service-packetbeat.ps1`. - -endif::[] - -Before starting Packetbeat, you should look at the configuration options in the -configuration file, for example `C:\Program Files\Packetbeat\packetbeat.yml` or `/etc/packetbeat/packetbeat.yml`. For -more information about these options, see <>. - -[[packetbeat-configuration]] -=== Step 2: Configure Packetbeat - -include::{libbeat-dir}/shared-configuring.asciidoc[] - -To configure Packetbeat: - -. Select the network interface from which to capture the traffic. - -* On -Linux: Packetbeat supports capturing all messages sent or received by the -server on which Packetbeat is installed. For this, use `any` as the device: -+ -[source,yaml] ----------------------------------------------------------------------- -packetbeat.interfaces.device: any ----------------------------------------------------------------------- - -* On OS X, capturing from the `any` device doesn't work. You would -typically use either `lo0` or `en0` depending on which traffic you want to -capture. - -* On Windows, run the following command to list the available network interfaces: -+ -[source,shell] ----------------------------------------------------------------------- -PS C:\Program Files\Packetbeat> .\packetbeat.exe devices - -0: \Device\NPF_{113535AD-934A-452E-8D5F-3004797DE286} (Intel(R) PRO/1000 MT Desktop Adapter) ----------------------------------------------------------------------- -+ -In this example, there's only one network card, with the index 0, installed on the system. If -there are multiple network cards, remember the index of the device you want to use for -capturing the traffic. -+ -Modify the `device` line to point to the index of the device: -+ -[source,yml] ----------------------------------------------------------------------- -packetbeat.interfaces.device: 0 ----------------------------------------------------------------------- - -. In the protocols section, configure the ports on which Packetbeat can find each -protocol. If you use any non-standard ports, add them here. Otherwise, the -default values should do just fine. -+ -[source,yaml] ----------------------------------------------------------------------- -packetbeat.protocols: - -- type: dhcpv4 - ports: [67, 68] - -- type: dns - ports: [53] - -- type: http - ports: [80, 8080, 8081, 5000, 8002] - -- type: memcache - ports: [11211] - -- type: mysql - ports: [3306,3307] - -- type: pgsql - ports: [5432] - -- type: redis - ports: [6379] - -- type: thrift - ports: [9090] - -- type: mongodb - ports: [27017] - -- type: cassandra - ports: [9042] - -- type: tls - ports: [443, 993, 995, 5223, 8443, 8883, 9243] - ----------------------------------------------------------------------- -+ -include::{libbeat-dir}/step-configure-output.asciidoc[] - -include::{libbeat-dir}/step-configure-kibana-endpoint.asciidoc[] - -include::{libbeat-dir}/step-configure-credentials.asciidoc[] - -include::{libbeat-dir}/step-test-config.asciidoc[] - -include::{libbeat-dir}/step-look-at-config.asciidoc[] - -[[packetbeat-template]] -=== Step 3: Load the index template in Elasticsearch - -include::{libbeat-dir}/shared-template-load.asciidoc[] - -[[load-kibana-dashboards]] -=== Step 4: Set up the Kibana dashboards - -include::{libbeat-dir}/dashboards.asciidoc[] - -[[packetbeat-starting]] -=== Step 5: Start Packetbeat - -Run Packetbeat by issuing the command that is appropriate for your platform. If -you are accessing a secured Elasticsearch cluster, make sure you've configured -credentials as described in <<{beatname_lc}-configuration>>. - -NOTE: If you use an init.d script to start Packetbeat on deb or rpm, you can't -specify command line flags (see <>). To specify flags, -start Packetbeat in the foreground. - -*deb and rpm:* - -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -sudo service {beatname_lc} start ----------------------------------------------------------------------- - -*docker:* - -See <>. - -*mac and linux:* - -[source,shell] ----------------------------------------------------------------------- -sudo chown root packetbeat.yml <1> -sudo ./packetbeat -e ----------------------------------------------------------------------- -<1> You'll be running Packetbeat as root, so you need to change ownership of the -configuration file, or run Packetbeat with `--strict.perms=false` specified. See -{beats-ref}/config-file-permissions.html[Config File Ownership and Permissions]in -the _Beats Platform Reference_. - -include::{libbeat-dir}/shared-brew-run.asciidoc[] - -*win:* - -[source,shell] ----------------------------------------------------------------------- -PS C:\Program Files\Packetbeat> Start-Service packetbeat ----------------------------------------------------------------------- - -By default the log files are stored in `C:\ProgramData\packetbeat\Logs`. - -==== Test the Packetbeat installation - -Packetbeat is now ready to capture data from your network traffic. You can test -that it works by creating a simple HTTP request. For example: - -[source,shell] ----------------------------------------------------------------------- -curl http://www.elastic.co/ > /dev/null ----------------------------------------------------------------------- - -Now verify that the data is present in Elasticsearch by issuing the following command: - -[source,shell] ----------------------------------------------------------------------- -curl -XGET 'http://localhost:9200/packetbeat-*/_search?pretty' ----------------------------------------------------------------------- - -Make sure that you replace `localhost:9200` with the address of your Elasticsearch -instance. The command should return data about the HTTP transaction you just created. - -[[view-kibana-dashboards]] -=== Step 6: View the sample Kibana dashboards - -To make it easier for you to get application performance insights -from packet data, we have created example {beatname_uc} dashboards. You loaded -the dashboards earlier when you ran the `setup` command. - -include::{libbeat-dir}/opendashboards.asciidoc[] - -The dashboards are provided as examples. We recommend that you -{kibana-ref}/dashboard.html[customize] them to meet your needs. - -TIP: To populate the client locations map in the overview dashboard, follow the -steps described in <<{beatname_lc}-geoip>>. - -[role="screenshot"] -image::./images/packetbeat-statistics.png[Packetbeat statistics] diff --git a/packetbeat/docs/howto/howto.asciidoc b/packetbeat/docs/howto/howto.asciidoc index 9d5f81d126c..cdadf3cb7b3 100644 --- a/packetbeat/docs/howto/howto.asciidoc +++ b/packetbeat/docs/howto/howto.asciidoc @@ -5,6 +5,9 @@ -- Learn how to perform common {beatname_uc} configuration tasks. +* <<{beatname_lc}-template>> +* <> +* <> * <<{beatname_lc}-geoip>> * <> * <> @@ -12,21 +15,22 @@ Learn how to perform common {beatname_uc} configuration tasks. -- +include::{libbeat-dir}/howto/load-index-templates.asciidoc[] + +include::{libbeat-dir}/howto/change-index-name.asciidoc[] + +include::{libbeat-dir}/howto/load-dashboards.asciidoc[] -[role="xpack"] include::{libbeat-dir}/shared-geoip.asciidoc[] :standalone: -[role="xpack"] include::{libbeat-dir}/shared-env-vars.asciidoc[] :standalone!: -[role="xpack"] include::{libbeat-dir}/shared-config-ingest.asciidoc[] :standalone: :allplatforms: -[role="xpack"] include::{libbeat-dir}/yaml.asciidoc[] :standalone!: :allplatforms!: diff --git a/packetbeat/docs/images/kibana-created-indexes.png b/packetbeat/docs/images/kibana-created-indexes.png deleted file mode 100644 index efed361d5ac..00000000000 Binary files a/packetbeat/docs/images/kibana-created-indexes.png and /dev/null differ diff --git a/packetbeat/docs/images/kibana-navigation-vis.png b/packetbeat/docs/images/kibana-navigation-vis.png deleted file mode 100644 index 49b9b353a22..00000000000 Binary files a/packetbeat/docs/images/kibana-navigation-vis.png and /dev/null differ diff --git a/packetbeat/docs/images/packetbeat-overview-dashboard.png b/packetbeat/docs/images/packetbeat-overview-dashboard.png new file mode 100644 index 00000000000..88a0b540c80 Binary files /dev/null and b/packetbeat/docs/images/packetbeat-overview-dashboard.png differ diff --git a/packetbeat/docs/index.asciidoc b/packetbeat/docs/index.asciidoc index c3c3a280241..5f1da41e677 100644 --- a/packetbeat/docs/index.asciidoc +++ b/packetbeat/docs/index.asciidoc @@ -31,9 +31,7 @@ include::{libbeat-dir}/shared-beats-attributes.asciidoc[] include::./overview.asciidoc[] -include::./gettingstarted.asciidoc[] - -include::{libbeat-dir}/repositories.asciidoc[] +include::./getting-started.asciidoc[] include::./setting-up-running.asciidoc[] @@ -58,3 +56,5 @@ include::./troubleshooting.asciidoc[] include::./faq.asciidoc[] include::{libbeat-dir}/contributing-to-beats.asciidoc[] + +include::{libbeat-dir}/shared/redirects.asciidoc[] diff --git a/packetbeat/docs/overview.asciidoc b/packetbeat/docs/overview.asciidoc index b0797cdcab7..6df6af54254 100644 --- a/packetbeat/docs/overview.asciidoc +++ b/packetbeat/docs/overview.asciidoc @@ -1,10 +1,6 @@ [[packetbeat-overview]] == Packetbeat overview -++++ -Overview -++++ - Packetbeat is a real-time network packet analyzer that you can use with Elasticsearch to provide an _application monitoring and performance analytics system_. Packetbeat completes the {beats-ref}/index.html[Beats platform] diff --git a/packetbeat/docs/setting-up-running.asciidoc b/packetbeat/docs/setting-up-running.asciidoc index 9808c01bc7f..42f941ee916 100644 --- a/packetbeat/docs/setting-up-running.asciidoc +++ b/packetbeat/docs/setting-up-running.asciidoc @@ -11,21 +11,27 @@ Set up and run ++++ -Before reading this section, see the -<<{beatname_lc}-getting-started,getting started documentation>> for basic +Before reading this section, see +<<{beatname_lc}-installation-configuration>> for basic installation instructions to get you started. -This section includes additional information on how to set up and run +This section includes additional information on how to install, set up, and run {beatname_uc}, including: * <> * <> +* <> + * <> * <> +* <<{beatname_lc}-starting>> + +* <> + //MAINTAINERS: If you add a new file to this section, make sure you update the bulleted list ^^ too. include::{libbeat-dir}/shared-directory-layout.asciidoc[] @@ -34,8 +40,12 @@ include::{libbeat-dir}/keystore.asciidoc[] include::{libbeat-dir}/command-reference.asciidoc[] +include::{libbeat-dir}/repositories.asciidoc[] + include::./running-on-docker.asciidoc[] include::{libbeat-dir}/shared-systemd.asciidoc[] -include::{libbeat-dir}/shared-shutdown.asciidoc[] +include::{libbeat-dir}/shared/start-beat.asciidoc[] + +include::{libbeat-dir}/shared/shutdown.asciidoc[] diff --git a/packetbeat/docs/tab-widgets/devices-widget.asciidoc b/packetbeat/docs/tab-widgets/devices-widget.asciidoc new file mode 100644 index 00000000000..4c4de0e5ec5 --- /dev/null +++ b/packetbeat/docs/tab-widgets/devices-widget.asciidoc @@ -0,0 +1,112 @@ +++++ +
+
+ + + + + + +
+
+++++ + +include::devices.asciidoc[tag=deb] + +++++ +
+ + + + + +
+++++ diff --git a/packetbeat/docs/tab-widgets/devices.asciidoc b/packetbeat/docs/tab-widgets/devices.asciidoc new file mode 100644 index 00000000000..597d603bf2d --- /dev/null +++ b/packetbeat/docs/tab-widgets/devices.asciidoc @@ -0,0 +1,54 @@ +// tag::deb[] +[source,shell] +------------------------------------------------ +packetbeat devices +------------------------------------------------ +// end::deb[] + +// tag::rpm[] +[source,shell] +------------------------------------------------ +packetbeat devices +------------------------------------------------ +// end::rpm[] + +// tag::mac[] +[source,shell] +------------------------------------------------ +./packetbeat devices +------------------------------------------------ +// end::mac[] + +// tag::brew[] +[source,shell] +------------------------- +packetbeat devices +------------------------- +// end::brew[] + +// tag::linux[] +[source,shell] +---------------------------------------------------------------------- +./packetbeat devices +---------------------------------------------------------------------- +// end::linux[] + +// tag::win[] +[source,shell] +---------------------------------------------------------------------- +PS C:\Program Files\Packetbeat> .\packetbeat.exe devices + +0: \Device\NPF_{113535AD-934A-452E-8D5F-3004797DE286} (Intel(R) PRO/1000 MT Desktop Adapter) +---------------------------------------------------------------------- + +In this example, there's only one network card, with the index 0, installed on +the system. If there are multiple network cards, remember the index of the +device you want to use for capturing the traffic. + +Modify the `device` setting to point to the index of the device: + +[source,shell] +---------------------------------------------------------------------- +packetbeat.interfaces.device: 0 +---------------------------------------------------------------------- +// end::win[] diff --git a/packetbeat/docs/tab-widgets/install-libpcap-widget.asciidoc b/packetbeat/docs/tab-widgets/install-libpcap-widget.asciidoc new file mode 100644 index 00000000000..1c7fb91cd23 --- /dev/null +++ b/packetbeat/docs/tab-widgets/install-libpcap-widget.asciidoc @@ -0,0 +1,112 @@ +++++ +
+
+ + + + + + +
+
+++++ + +include::install-libpcap.asciidoc[tag=deb] + +++++ +
+ + + + + +
+++++ diff --git a/packetbeat/docs/tab-widgets/install-libpcap.asciidoc b/packetbeat/docs/tab-widgets/install-libpcap.asciidoc new file mode 100644 index 00000000000..d23d2f23696 --- /dev/null +++ b/packetbeat/docs/tab-widgets/install-libpcap.asciidoc @@ -0,0 +1,37 @@ +:no-libpcap: + +// tag::deb[] +["source","sh",subs="attributes"] +------------------------------------------------ +sudo apt-get install libpcap{libpcap} +------------------------------------------------ +// end::deb[] + +// tag::rpm[] +["source","sh",subs="attributes"] +------------------------------------------------ +sudo yum install libpcap +------------------------------------------------ +// end::rpm[] + +// tag::mac[] +You probably do not need to install libpcap. +// end::mac[] + +// tag::brew[] +You probably do not need to install libpcap. +// end::brew[] + +// tag::linux[] +You probably do not need to install libpcap. +// end::linux[] + +// tag::win[] +Download and install a packet sniffing library, +such as https://nmap.org/npcap/[Npcap], that implements the +https://github.com/the-tcpdump-group/libpcap[libpcap] interfaces. + +If you use Npcap, make sure you install it in WinPcap API-compatible mode. If +you plan to capture traffic from the loopback device (127.0.0.1 traffic), also +select the option to support loopback traffic. +// end::win[] diff --git a/packetbeat/docs/upgrading.asciidoc b/packetbeat/docs/upgrading.asciidoc index f7fd8010f34..45afca1ac04 100644 --- a/packetbeat/docs/upgrading.asciidoc +++ b/packetbeat/docs/upgrading.asciidoc @@ -1,7 +1,7 @@ [[upgrading-packetbeat]] == Upgrade Packetbeat -For information about upgrading to a new version, see the following topics in the _Beats Platform Reference_: +For information about upgrading to a new version, see: * {beats-ref}/breaking-changes.html[Breaking Changes] * {beats-ref}/upgrading.html[Upgrade] diff --git a/winlogbeat/docs/configuring-howto.asciidoc b/winlogbeat/docs/configuring-howto.asciidoc index dc622427b48..d0447dc3099 100644 --- a/winlogbeat/docs/configuring-howto.asciidoc +++ b/winlogbeat/docs/configuring-howto.asciidoc @@ -7,19 +7,7 @@ Configure ++++ -Before modifying configuration settings, make sure you've completed the -<> in the Getting Started. -This section describes some common use cases for changing configuration options. - -To configure {beatname_uc}, you edit the configuration file. You’ll find the configuration file, -+{beatname_lc}.yml+, in the archive that you extracted. There's also a full example configuration file at -+/etc/{beatname_lc}/{beatname_lc}.reference.yml+ that shows all non-deprecated options. - -The {beatname_uc} configuration file uses http://yaml.org/[YAML] for its syntax. See the -{beats-ref}/config-file-format.html[Config File Format] section of the -_Beats Platform Reference_ for more about the structure of the config file. - -The following topics describe how to configure Winlogbeat: +include::{libbeat-dir}/shared/configuring-intro.asciidoc[] * <> * <> diff --git a/winlogbeat/docs/getting-started.asciidoc b/winlogbeat/docs/getting-started.asciidoc index 4ccb1f6e02d..95d96181b73 100644 --- a/winlogbeat/docs/getting-started.asciidoc +++ b/winlogbeat/docs/getting-started.asciidoc @@ -1,27 +1,34 @@ -[[winlogbeat-getting-started]] -== Get started with {beatname_uc} +[id="{beatname_lc}-installation-configuration"] +== {beatname_uc} quick start: installation and configuration ++++ -Get started +Quick start: installation and configuration ++++ -include::{libbeat-dir}/shared-getting-started-intro.asciidoc[] +This guide describes how to get started quickly with Windows log monitoring. +You'll learn how to: -* <> -* <> -* <> -* <> -* <> -* <> -* <> +* install {beatname_uc} on each system you want to monitor +* specify the location of your log files +* parse log data into fields and send it to {es} +* visualize the log data in {kib} -[[winlogbeat-installation]] -=== Step 1: Install Winlogbeat +[role="screenshot"] +image::./images/winlogbeat-dashboard.png[{beatname_uc} dashboard] + +[float] +=== Before you begin + +You need {es} for storing and searching your data, and {kib} for visualizing and +managing it. -*Before you begin*: If you haven't installed the {stack}, do that now. See -{stack-gs}/get-started-elastic-stack.html[Get started with the {stack}]. +include::{libbeat-dir}/tab-widgets/spinup-stack-widget.asciidoc[] -. Download the Winlogbeat zip file from the +[float] +[[installation]] +=== Step 1: Install {beatname_uc} + +. Download the {beatname_uc} zip file from the https://www.elastic.co/downloads/beats/winlogbeat[downloads page]. . Extract the contents into `C:\Program Files`. . Rename the `winlogbeat-` directory to `Winlogbeat`. @@ -30,7 +37,7 @@ icon and select Run As Administrator). . From the PowerShell prompt, run the following commands to install the service. ["source","sh",subs="attributes,callouts"] ------------------------------------------------- +---- PS C:\Users\Administrator> cd 'C:\Program Files\Winlogbeat' PS C:\Program Files\Winlogbeat> .\install-service-winlogbeat.ps1 @@ -44,103 +51,111 @@ Do you want to run C:\Program Files\Winlogbeat\install-service-winlogbeat.ps1? Status Name DisplayName ------ ---- ----------- Stopped winlogbeat winlogbeat ------------------------------------------------- +---- NOTE: If script execution is disabled on your system, you need to set the execution policy for the current session to allow the script to run. For example: `PowerShell.exe -ExecutionPolicy UnRestricted -File .\install-service-winlogbeat.ps1`. -Before starting Winlogbeat, you should look at the configuration options in the -configuration file, for example `C:\Program Files\Winlogbeat\winlogbeat.yml`. -There’s also a full example configuration file called `winlogbeat.reference.yml` that -shows all non-deprecated options. For more information about these options, see -<>. - -[[winlogbeat-configuration]] -=== Step 2: Configure Winlogbeat +[float] +[[set-connection]] +=== Step 2: Connect to the {stack} -To configure Winlogbeat, you edit the `winlogbeat.yml` configuration file. See the -{beats-ref}/config-file-format.html[Config File Format] section of the -_Beats Platform Reference_ for more about the structure of the config file. +include::{libbeat-dir}/shared/connecting-to-es.asciidoc[] -Here is a sample of the `winlogbeat.yml` file: +[float] +[[configuration]] +=== Step 3: Configure {beatname_uc} -[source,yaml] --------------------------------------------------------------------------------- -winlogbeat.event_logs: - - name: Application - - name: Security - - name: System +In `winlogbeat.yml`, configure the event logs that you want to monitor. -output.elasticsearch: - hosts: - - localhost:9200 - -logging.to_files: true -logging.files: - path: C:\ProgramData\winlogbeat\Logs -logging.level: info --------------------------------------------------------------------------------- - -To configure Winlogbeat: - -. In the `event_logs` section, specify the event logs that you want to monitor. -By default, Winlogbeat is set to monitor application, security, and system logs: +. Under `winlogbeat.event_log`, specify a list of event logs to monitor. By +default, {beatname_uc} monitors application, security, and system logs. + [source,yaml] ----------------------------------------------------------------------- +---- winlogbeat.event_logs: - name: Application - name: Security - name: System ----------------------------------------------------------------------- +---- + To obtain a list of available event logs, run `Get-EventLog *` in PowerShell. For more information about this command, see the configuration details for <>. -include::{libbeat-dir}/step-configure-output.asciidoc[] - -include::{libbeat-dir}/step-configure-kibana-endpoint.asciidoc[] - -include::{libbeat-dir}/step-configure-credentials.asciidoc[] +. (Optional) Set logging options to write Winlogbeat logs to a file: ++ +[source,yaml] +---- +logging.to_files: true +logging.files: + path: C:\ProgramData\winlogbeat\Logs +logging.level: info +---- . After you save your configuration file, test it with the following command. + [source,shell] ----------------------------------------------------------------------- +---- PS C:\Program Files\Winlogbeat> .\winlogbeat.exe test config -c .\winlogbeat.yml -e ----------------------------------------------------------------------- +---- -[[config-winlogbeat-logstash]] -=== Step 3: Configure Winlogbeat to use Logstash -include::{libbeat-outputs-dir}/logstash/docs/logstash.asciidoc[tag=shared-logstash-config] +For more information about configuring {beatname_uc}, also see: -[[winlogbeat-template]] -=== Step 4: Load the index template in Elasticsearch +* <> +* {beats-ref}/config-file-format.html[Config file format] +ifeval::["{beatname_lc}"!="apm-server"] +* <<{beatname_lc}-reference-yml,+{beatname_lc}.reference.yml+>>: This reference configuration +file shows all non-deprecated options. You'll find it in the same location as ++{beatname_lc}.yml+. -include::{libbeat-dir}/shared-template-load.asciidoc[] +[float] +[[setup-assets]] +=== Step 4: Set up assets -[[load-kibana-dashboards]] -=== Step 5: Set up the Kibana dashboards +{beatname_uc} comes with predefined assets for parsing, indexing, and +visualizing your data. To load these assets: -include::{libbeat-dir}/dashboards.asciidoc[] +. Make sure the user specified in +{beatname_lc}.yml+ is +<>. -[[winlogbeat-starting]] -=== Step 6: Start Winlogbeat +. From the installation directory, run: ++ +-- +include::{libbeat-dir}/tab-widgets/setup.asciidoc[tag=win] +-- + +This step loads the recommended {ref}/indices-templates.html[index template] for writing to {es} +and deploys the sample dashboards for visualizing the data in {kib}. + +[TIP] +===== +A connection to {es} (or {ess}) is required to set up the initial +environment. If you're using a different output, such as {ls}, see +<> and <>. +===== + +[float] +[[start]] +=== Step 5: Start {beatname_uc} + +Before starting {beatname_uc}, modify the user credentials in ++{beatname_lc}.yml+ and specify a user who is +<>. -Start the Winlogbeat service with the following command. If you are accessing a -secured Elasticsearch cluster, make sure you've configured credentials as -described in <<{beatname_lc}-configuration>>. +To start the {beatname_uc} service, run: +// tag::start-step[] [source,shell] ---------------------------------------------------------------------- PS C:\Program Files\Winlogbeat> Start-Service winlogbeat ---------------------------------------------------------------------- -Winlogbeat should now be running. If you used the configuration described here, -then you can view the log file at `C:\ProgramData\winlogbeat\Logs\winlogbeat`. +{beatname_uc} should now be running. If you used the logging configuration +described here, you can view the log file at +`C:\ProgramData\winlogbeat\Logs\winlogbeat`. You can view the status of the service and control it from the Services management console in Windows. To launch the management console, run @@ -150,28 +165,33 @@ this command: ---------------------------------------------------------------------- PS C:\Program Files\Winlogbeat> services.msc ---------------------------------------------------------------------- +// end::start-step[] +[float] +==== Stop {beatname_uc} -==== Stop Winlogbeat - -Stop the Winlogbeat service with the following command: +Stop the {beatname_uc} service with the following command: [source,shell] ---------------------------------------------------------------------- PS C:\Program Files\Winlogbeat> Stop-Service winlogbeat ---------------------------------------------------------------------- -[[view-kibana-dashboards]] -=== Step 7: View the sample Kibana dashboards +[float] +[[view-data]] +=== Step 6: View your data in {kib} -To make it easier for you to start monitoring your servers in Kibana, we have -created example {beatname_uc} dashboards. You loaded the dashboards earlier -when you ran the `setup` command. +include::{libbeat-dir}/shared/opendashboards.asciidoc[tag=open-dashboards-intro] -include::{libbeat-dir}/opendashboards.asciidoc[] +include::{libbeat-dir}/shared/opendashboards.asciidoc[tag=open-dashboards] -The dashboards are provided as examples. We recommend that you -{kibana-ref}/dashboard.html[customize] them to meet your needs. +[float] +=== What's next? -[role="screenshot"] -image::./images/winlogbeat-dashboard.png[Winlogbeat statistics] +Now that you have your logs streaming into {es}, learn how to unify your logs, +metrics, uptime, and application performance data. + +include::{libbeat-dir}/shared/obs-apps.asciidoc[] + +// Add Javascript and CSS for tabbed panels +include::{libbeat-dir}/tab-widgets/code.asciidoc[] diff --git a/winlogbeat/docs/howto/howto.asciidoc b/winlogbeat/docs/howto/howto.asciidoc index 54eef117163..9cadd46f71e 100644 --- a/winlogbeat/docs/howto/howto.asciidoc +++ b/winlogbeat/docs/howto/howto.asciidoc @@ -6,6 +6,9 @@ Learn how to perform common {beatname_uc} configuration tasks. * <<{beatname_lc}-geoip>> +* <<{beatname_lc}-template>> +* <> +* <> * <> * <> * <> @@ -15,6 +18,12 @@ Learn how to perform common {beatname_uc} configuration tasks. include::{libbeat-dir}/shared-geoip.asciidoc[] +include::{libbeat-dir}/howto/load-index-templates.asciidoc[] + +include::{libbeat-dir}/howto/change-index-name.asciidoc[] + +include::{libbeat-dir}/howto/load-dashboards.asciidoc[] + :standalone: include::{libbeat-dir}/shared-env-vars.asciidoc[] :standalone!: diff --git a/winlogbeat/docs/images/kibana-created-indexes.png b/winlogbeat/docs/images/kibana-created-indexes.png deleted file mode 100755 index 648fdc93961..00000000000 Binary files a/winlogbeat/docs/images/kibana-created-indexes.png and /dev/null differ diff --git a/winlogbeat/docs/images/kibana-navigation-vis.png b/winlogbeat/docs/images/kibana-navigation-vis.png deleted file mode 100755 index 820b97a9d26..00000000000 Binary files a/winlogbeat/docs/images/kibana-navigation-vis.png and /dev/null differ diff --git a/winlogbeat/docs/images/winlogbeat-dashboard.png b/winlogbeat/docs/images/winlogbeat-dashboard.png index ddeaed7842d..714edcdf75d 100644 Binary files a/winlogbeat/docs/images/winlogbeat-dashboard.png and b/winlogbeat/docs/images/winlogbeat-dashboard.png differ diff --git a/winlogbeat/docs/index.asciidoc b/winlogbeat/docs/index.asciidoc index 6f4f6836e65..e92cdcc3df6 100644 --- a/winlogbeat/docs/index.asciidoc +++ b/winlogbeat/docs/index.asciidoc @@ -50,3 +50,4 @@ include::./faq.asciidoc[] include::{libbeat-dir}/contributing-to-beats.asciidoc[] +include::{libbeat-dir}/shared/redirects.asciidoc[] diff --git a/winlogbeat/docs/overview.asciidoc b/winlogbeat/docs/overview.asciidoc index 04f9cd5f786..aef277fa319 100644 --- a/winlogbeat/docs/overview.asciidoc +++ b/winlogbeat/docs/overview.asciidoc @@ -1,9 +1,5 @@ == Winlogbeat Overview -++++ -Overview -++++ - Winlogbeat ships Windows event logs to Elasticsearch or Logstash. You can install it as a Windows service. diff --git a/winlogbeat/docs/setting-up-running.asciidoc b/winlogbeat/docs/setting-up-running.asciidoc index e227c9a8457..fe31d8e41fd 100644 --- a/winlogbeat/docs/setting-up-running.asciidoc +++ b/winlogbeat/docs/setting-up-running.asciidoc @@ -11,17 +11,24 @@ Set up and run ++++ -Before reading this section, see the -<<{beatname_lc}-getting-started,getting started documentation>> for basic +Before reading this section, see +<<{beatname_lc}-installation-configuration>> for basic installation instructions to get you started. -This section includes additional information on how to set up and run +This section includes additional information on how to install, set up, and run {beatname_uc}, including: * <> +* <> + * <> +* <<{beatname_lc}-starting>> + +* <> + + //MAINTAINERS: If you add a new file to this section, make sure you update the bulleted list ^^ too. include::{libbeat-dir}/shared-directory-layout.asciidoc[] @@ -30,4 +37,6 @@ include::{libbeat-dir}/keystore.asciidoc[] include::{libbeat-dir}/command-reference.asciidoc[] -include::{libbeat-dir}/shared-shutdown.asciidoc[] +include::{libbeat-dir}/shared/start-beat.asciidoc[] + +include::{libbeat-dir}/shared/shutdown.asciidoc[] diff --git a/winlogbeat/docs/upgrading.asciidoc b/winlogbeat/docs/upgrading.asciidoc index 3101f90f252..8a6bca81cf2 100644 --- a/winlogbeat/docs/upgrading.asciidoc +++ b/winlogbeat/docs/upgrading.asciidoc @@ -5,7 +5,7 @@ Upgrade ++++ -For information about upgrading to a new version, see the following topics in the _Beats Platform Reference_: +For information about upgrading to a new version, see: * {beats-ref}/breaking-changes.html[Breaking Changes] * {beats-ref}/upgrading.html[Upgrade] diff --git a/x-pack/dockerlogbeat/docs/overview.asciidoc b/x-pack/dockerlogbeat/docs/overview.asciidoc index 78bc7692865..9a4ff848c6e 100644 --- a/x-pack/dockerlogbeat/docs/overview.asciidoc +++ b/x-pack/dockerlogbeat/docs/overview.asciidoc @@ -2,10 +2,6 @@ [role="xpack"] == {log-driver} overview -++++ -Overview -++++ - experimental[] The {log-driver} is a Docker plugin that sends container logs to the diff --git a/x-pack/filebeat/module/crowdstrike/_meta/docs.asciidoc b/x-pack/filebeat/module/crowdstrike/_meta/docs.asciidoc index 470462582e6..0164a567556 100644 --- a/x-pack/filebeat/module/crowdstrike/_meta/docs.asciidoc +++ b/x-pack/filebeat/module/crowdstrike/_meta/docs.asciidoc @@ -5,36 +5,19 @@ == Crowdstrike module -This is the filebeat module for the Crowdstrike Falcon using the Falcon https://www.crowdstrike.com/blog/tech-center/integrate-with-your-siem[SIEM Connector]. This module collects this data, converts it to ECS, and ingests it to view in the SIEM. By default, the Falcon SIEM connector outputs JSON formatted Falcon Streaming API event data. +This is the {beatname_uc} module for CrowdStrike Falcon using the Falcon https://www.crowdstrike.com/blog/tech-center/integrate-with-your-siem[SIEM Connector]. This module collects this data, converts it to ECS, and ingests it to view in the SIEM. By default, the Falcon SIEM connector outputs JSON formatted Falcon Streaming API event data. This module segments events forwarded by the Falcon SIEM connector into two datasets for endpoint data and Falcon platform audit data. include::../include/what-happens.asciidoc[] +include::../include/gs-link.asciidoc[] + [float] === Compatibility This input supports Crowdstrike Falcon SIEM-Connector-v2.0. -include::../include/running-modules.asciidoc[] - -[float] -=== Dashboards - -The best way to view Crowdstrike events and alert data is in the SIEM. - -[role="screenshot"] -image::./images/siem-alerts-cs.jpg[] - -[float] -For alerts, go to Detections -> External alerts. - -[role="screenshot"] -image::./images/siem-events-cs.jpg[] - -[float] -And for all over event Crowdstrike Falcon event types, go to Host -> Events. - include::../include/configuring-intro.asciidoc[] :fileset_ex: falcon_endpoint @@ -56,6 +39,24 @@ var: include::../include/var-paths.asciidoc[] +[float] +=== Dashboards + +The best way to view CrowdStrike events and alert data is in the SIEM. + +[role="screenshot"] +image::./images/siem-alerts-cs.jpg[] + +[float] +For alerts, go to Detections -> External alerts. + +[role="screenshot"] +image::./images/siem-events-cs.jpg[] + +[float] +And for all over event CrowdStrike Falcon event types, go to Host -> Events. + + :has-dashboards!: :modulename!: diff --git a/x-pack/functionbeat/docs/configuring-howto.asciidoc b/x-pack/functionbeat/docs/configuring-howto.asciidoc index 03e3d777072..ff0525cecb0 100644 --- a/x-pack/functionbeat/docs/configuring-howto.asciidoc +++ b/x-pack/functionbeat/docs/configuring-howto.asciidoc @@ -8,13 +8,7 @@ Configure ++++ -Before modifying configuration settings, make sure you've completed the -<<{beatname_lc}-configuration,configuration steps>> in the Getting Started. -This section describes some common use cases for changing configuration options. - -include::{libbeat-dir}/shared-configuring.asciidoc[] - -The following topics describe how to configure {beatname_uc}: +include::{libbeat-dir}/shared/configuring-intro.asciidoc[] * <> * <> diff --git a/x-pack/functionbeat/docs/getting-started.asciidoc b/x-pack/functionbeat/docs/getting-started.asciidoc index b0264f694cc..681fc127853 100644 --- a/x-pack/functionbeat/docs/getting-started.asciidoc +++ b/x-pack/functionbeat/docs/getting-started.asciidoc @@ -1,21 +1,24 @@ -[id="{beatname_lc}-getting-started"] +[id="{beatname_lc}-installation-configuration"] [role="xpack"] -== Get started with {beatname_uc} +== {beatname_uc} quick start: installation and configuration ++++ -Get started +Quick start: installation and configuration ++++ -include::{libbeat-dir}/shared-getting-started-intro.asciidoc[] +This guide describes how to get started quickly monitoring data from your cloud +services. You'll learn how to: -* <<{beatname_lc}-installation>> -* <<{beatname_lc}-configuration>> -* <<{beatname_lc}-template>> -* <<{beatname_lc}-deploying>> -* <> -[id="{beatname_lc}-installation"] -[role="xpack"] +* download the {beatname_uc} distribution +* configure details about the cloud functions you want to deploy, including the +services to monitor and triggers +* deploy the cloud functions to your serverless environment +* collect data from cloud services and ship it to the {stack} +* visualize the data in {kib} + +[float] +[[install]] === Step 1: Download {beatname_uc} The {beatname_uc} distribution contains the command line tools, configuration @@ -25,81 +28,26 @@ environment. To download and extract the package, use the commands that work with your system. -[[linux]] -*linux:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes"] ------------------------------------------------- -curl -L -O https://artifacts.elastic.co/downloads/beats/{beatname_lc}/{beatname_lc}-{version}-linux-x86_64.tar.gz -tar xzvf {beatname_lc}-{version}-linux-x86_64.tar.gz ------------------------------------------------- - -endif::[] - -[[mac]] -*mac:* - -ifeval::["{release-state}"=="unreleased"] - -Version {version} of {beatname_uc} has not yet been released. - -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -["source","sh",subs="attributes"] ------------------------------------------------- -curl -L -O https://artifacts.elastic.co/downloads/beats/{beatname_lc}/{beatname_lc}-{version}-darwin-x86_64.tar.gz -tar xzvf {beatname_lc}-{version}-darwin-x86_64.tar.gz ------------------------------------------------- - -endif::[] - -[[win]] -*win:* +include::{libbeat-dir}/tab-widgets/install-linux-mac-win-short-widget.asciidoc[] -ifeval::["{release-state}"=="unreleased"] +[float] +[[set-connection]] +=== Step 2: Connect to the {stack} -Version {version} of {beatname_uc} has not yet been released. +include::{libbeat-dir}/shared/connecting-to-es.asciidoc[] -endif::[] - -ifeval::["{release-state}"!="unreleased"] - -. Download the {beatname_uc} Windows zip file from the -https://www.elastic.co/downloads/beats/{beatname_lc}[downloads page]. - -. Extract the contents of the zip file. - -endif::[] - -[id="{beatname_lc}-configuration"] -[role="xpack"] -=== Step 2: Configure {beatname_uc} +[float] +[[configuration]] +=== Step 3: Configure cloud functions Before deploying {beatname_uc} to your cloud provider, you need to specify details about the cloud functions that you want to deploy, including the function name and type, and the triggers that will cause the function to -execute. You also need to specify connection details for your {es} cluster. - -You specify settings in the +{beatname_lc}.yml+ configuration file. This file -is located in the archive that you extracted earlier. +execute. -TIP: See the -{beats-ref}/config-file-format.html[Config File Format] section of the -_Beats Platform Reference_ for more about the structure of the config file. - -. Configure the functions that you want to deploy. The configuration settings -vary depending on the type of function and cloud provider you're using. This -section provides a couple of example configurations. +. In +{beatname_lc}.yml+, configure the functions that you want to deploy. The +configuration settings vary depending on the type of function and cloud provider +you're using. This section provides a couple of example configurations. + -- * *AWS example*: This example configures a function called `cloudwatch` that @@ -156,24 +104,39 @@ See <> for more examples. -- -include::{libbeat-dir}/step-configure-output.asciidoc[] +include::{libbeat-dir}/shared/config-check.asciidoc[] -include::{libbeat-dir}/step-configure-credentials.asciidoc[] +[float] +[[setup-assets]] +=== Step 4: Set up assets -include::{libbeat-dir}/step-test-config.asciidoc[] +{beatname_uc} comes with predefined assets for parsing, indexing, and +visualizing your data. To load these assets: -include::{libbeat-dir}/step-look-at-config.asciidoc[] +. Make sure the user specified in +{beatname_lc}.yml+ is +<>. -[id="{beatname_lc}-template"] -[role="xpack"] -=== Step 3: Load the index template in Elasticsearch +. From the installation directory, run: ++ +-- +include::{libbeat-dir}/tab-widgets/setup-linux-mac-win-widget.asciidoc[] +-- ++ +`-e` is optional and sends output to standard error instead of the configured log output. -:allplatforms: -include::{libbeat-dir}/shared-template-load.asciidoc[] +This step loads the recommended {ref}/indices-templates.html[index template] for writing to {es}. +[TIP] +===== +A connection to {es} (or {ess}) is required to set up the initial +environment. If you're using a different output, such as {ls}, see +<>. +===== + +[float] [id="{beatname_lc}-deploying"] [role="xpack"] -=== Step 4: Deploy {beatname_uc} +=== Step 5: Deploy {beatname_uc} To deploy {beatname_uc} functions to your cloud provider, either use the {beatname_uc} manager, as described here, or <>. TIP: If you change the configuration after deploying the function, use the <> to update your deployment. +[float] [[deploy-to-aws]] ==== Deploy to AWS . Make sure you have the credentials required to authenticate with AWS. You can set environment variables that contain your credentials: + -*linux and mac*: -+ -[source, shell] ----- -export AWS_ACCESS_KEY_ID=ABCDEFGHIJKLMNOPUSER -export AWS_SECRET_ACCESS_KEY=EXAMPLE567890devgHIJKMLOPNQRSTUVZ1234KEY -export AWS_DEFAULT_REGION=us-east-1 ----- -+ -*win*: -+ -[source, shell] ----- -set AWS_ACCESS_KEY_ID=ABCDEFGHIJKLMNOPUSER -set AWS_SECRET_ACCESS_KEY=EXAMPLE567890devgHIJKMLOPNQRSTUVZ1234KEY -set AWS_DEFAULT_REGION=us-east-1 ----- +-- +include::tab-widgets/credentials-aws-widget.asciidoc[] +-- + Set `AWS_DEFAULT_REGION` to the region where your services are running. @@ -215,25 +165,18 @@ function. For more information, see <>. + For example, the following command deploys a function called `cloudwatch`: + -*linux and mac:* -+ -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -./{beatname_lc} -v -e -d "*" deploy cloudwatch ----------------------------------------------------------------------- -+ -*win:* -+ -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -.{backslash}{beatname_lc}.exe -v -e -d "*" deploy cloudwatch ----------------------------------------------------------------------- +-- +include::tab-widgets/deploy-aws-widget.asciidoc[] +-- + The function is deployed to AWS and ready to send log events to the configured output. + If deployment fails, see <> for help troubleshooting. +:fnexample!: + +[float] [[deploy-to-gcp]] ==== Deploy to Google Cloud Platform @@ -251,49 +194,39 @@ Cloud documentation] for more information about creating a service account. . Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to point to the JSON file that contains your service account key. For example: + -*linux and mac*: -+ -[source, shell] ----- -export GOOGLE_APPLICATION_CREDENTIALS="/path/to/myproject-5a90ee91d102.json" ----- -+ -*win*: -+ -[source, shell] ----- -set GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\myproject-5a90ee91d102.json" ----- +-- +include::tab-widgets/credentials-google-widget.asciidoc[] +-- . Deploy the cloud functions. + For example, the following command deploys a function called `storage`: + -*linux and mac:* -+ -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -./{beatname_lc} -v -e -d "*" deploy storage ----------------------------------------------------------------------- -+ -*win:* -+ -["source","sh",subs="attributes"] ----------------------------------------------------------------------- -.{backslash}{beatname_lc}.exe -v -e -d "*" deploy storage ----------------------------------------------------------------------- +-- +include::tab-widgets/deploy-google-widget.asciidoc[] +-- + The function is deployed to Google Cloud Platform and ready to send events to the configured output. + If deployment fails, see <> for help troubleshooting. -[[view-kibana-dashboards]] -[role="xpack"] -=== Step 5: View your data in Kibana +[float] +[[view-data]] +=== Step 6: View your data in {kib} There are currently no example dashboards available for {beatname_uc}. To learn how to view and explore your data, see the _{kibana-ref}/index.html[{kib} User Guide]_. +[float] +=== What's next? + +Now that you have your cloud data streaming into {es}, learn how to unify your +logs, metrics, uptime, and application performance data. + +include::{libbeat-dir}/shared/obs-apps.asciidoc[] + +// Add Javascript and CSS for tabbed panels +include::{libbeat-dir}/tab-widgets/code.asciidoc[] diff --git a/x-pack/functionbeat/docs/howto/howto.asciidoc b/x-pack/functionbeat/docs/howto/howto.asciidoc index 953d2a4c4f0..f116bc57d0c 100644 --- a/x-pack/functionbeat/docs/howto/howto.asciidoc +++ b/x-pack/functionbeat/docs/howto/howto.asciidoc @@ -6,6 +6,8 @@ -- Learn how to perform common {beatname_uc} configuration tasks. +* <<{beatname_lc}-template>> +* <> * <<{beatname_lc}-geoip>> * <> * <> @@ -14,6 +16,12 @@ Learn how to perform common {beatname_uc} configuration tasks. -- +[role="xpack"] +include::{libbeat-dir}/howto/load-index-templates.asciidoc[] + +[role="xpack"] +include::{libbeat-dir}/howto/change-index-name.asciidoc[] + [role="xpack"] include::{libbeat-dir}/shared-geoip.asciidoc[] diff --git a/x-pack/functionbeat/docs/index.asciidoc b/x-pack/functionbeat/docs/index.asciidoc index fc6a1f933d9..2d784e6d525 100644 --- a/x-pack/functionbeat/docs/index.asciidoc +++ b/x-pack/functionbeat/docs/index.asciidoc @@ -57,3 +57,4 @@ include::./troubleshooting.asciidoc[] include::./faq.asciidoc[] +include::{libbeat-dir}/shared/redirects.asciidoc[] diff --git a/x-pack/functionbeat/docs/overview.asciidoc b/x-pack/functionbeat/docs/overview.asciidoc index f5b39bf674c..685a9910253 100644 --- a/x-pack/functionbeat/docs/overview.asciidoc +++ b/x-pack/functionbeat/docs/overview.asciidoc @@ -2,10 +2,6 @@ [role="xpack"] == {beatname_uc} overview -++++ -Overview -++++ - {beatname_uc} is an Elastic https://www.elastic.co/products/beats[Beat] that you deploy as a function in your serverless environment to collect data from cloud services and ship it to the {stack}. diff --git a/x-pack/functionbeat/docs/setting-up-running.asciidoc b/x-pack/functionbeat/docs/setting-up-running.asciidoc index 878cacf3d3f..823bbbd4067 100644 --- a/x-pack/functionbeat/docs/setting-up-running.asciidoc +++ b/x-pack/functionbeat/docs/setting-up-running.asciidoc @@ -12,11 +12,11 @@ Set up and deploy ++++ -Before reading this section, see the -<<{beatname_lc}-getting-started,getting started documentation>> for basic +Before reading this section, see +<<{beatname_lc}-installation-configuration>> for basic installation instructions to get you started. -This section includes additional information on how to set up and run +This section includes additional information on how to install, set up, and run {beatname_uc}, including: * <> diff --git a/x-pack/functionbeat/docs/tab-widgets/credentials-aws-widget.asciidoc b/x-pack/functionbeat/docs/tab-widgets/credentials-aws-widget.asciidoc new file mode 100644 index 00000000000..d1db7f99189 --- /dev/null +++ b/x-pack/functionbeat/docs/tab-widgets/credentials-aws-widget.asciidoc @@ -0,0 +1,58 @@ +++++ +
+
+ + + +
+
+++++ + +include::credentials-aws.asciidoc[tag=mac] + +++++ +
+ + +
+++++ diff --git a/x-pack/functionbeat/docs/tab-widgets/credentials-aws.asciidoc b/x-pack/functionbeat/docs/tab-widgets/credentials-aws.asciidoc new file mode 100644 index 00000000000..16f330c906f --- /dev/null +++ b/x-pack/functionbeat/docs/tab-widgets/credentials-aws.asciidoc @@ -0,0 +1,26 @@ +// tag::mac[] +[source, shell] +---- +export AWS_ACCESS_KEY_ID=ABCDEFGHIJKLMNOPUSER +export AWS_SECRET_ACCESS_KEY=EXAMPLE567890devgHIJKMLOPNQRSTUVZ1234KEY +export AWS_DEFAULT_REGION=us-east-1 +---- +// end::mac[] + +// tag::linux[] +[source, shell] +---- +export AWS_ACCESS_KEY_ID=ABCDEFGHIJKLMNOPUSER +export AWS_SECRET_ACCESS_KEY=EXAMPLE567890devgHIJKMLOPNQRSTUVZ1234KEY +export AWS_DEFAULT_REGION=us-east-1 +---- +// end::linux[] + +// tag::win[] +[source, shell] +---- +set AWS_ACCESS_KEY_ID=ABCDEFGHIJKLMNOPUSER +set AWS_SECRET_ACCESS_KEY=EXAMPLE567890devgHIJKMLOPNQRSTUVZ1234KEY +set AWS_DEFAULT_REGION=us-east-1 +---- +// end::win[] diff --git a/x-pack/functionbeat/docs/tab-widgets/credentials-google-widget.asciidoc b/x-pack/functionbeat/docs/tab-widgets/credentials-google-widget.asciidoc new file mode 100644 index 00000000000..9802f925f0e --- /dev/null +++ b/x-pack/functionbeat/docs/tab-widgets/credentials-google-widget.asciidoc @@ -0,0 +1,58 @@ +++++ +
+
+ + + +
+
+++++ + +include::credentials-google.asciidoc[tag=mac] + +++++ +
+ + +
+++++ diff --git a/x-pack/functionbeat/docs/tab-widgets/credentials-google.asciidoc b/x-pack/functionbeat/docs/tab-widgets/credentials-google.asciidoc new file mode 100644 index 00000000000..9bfee91f0ce --- /dev/null +++ b/x-pack/functionbeat/docs/tab-widgets/credentials-google.asciidoc @@ -0,0 +1,19 @@ +// tag::mac[] +[source,shell] +---- +export GOOGLE_APPLICATION_CREDENTIALS="/path/to/myproject-5a90ee91d102.json" +---- +// end::mac[] + +// tag::linux[] +[source,shell] +---- +export GOOGLE_APPLICATION_CREDENTIALS="/path/to/myproject-5a90ee91d102.json" +---- +// end::linux[] +// tag::win[] +[source,shell] +---- +set GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\myproject-5a90ee91d102.json" +---- +// end::win[] diff --git a/x-pack/functionbeat/docs/tab-widgets/deploy-aws-widget.asciidoc b/x-pack/functionbeat/docs/tab-widgets/deploy-aws-widget.asciidoc new file mode 100644 index 00000000000..a6575c0e859 --- /dev/null +++ b/x-pack/functionbeat/docs/tab-widgets/deploy-aws-widget.asciidoc @@ -0,0 +1,58 @@ +++++ +
+
+ + + +
+
+++++ + +include::deploy-aws.asciidoc[tag=mac] + +++++ +
+ + +
+++++ diff --git a/x-pack/functionbeat/docs/tab-widgets/deploy-aws.asciidoc b/x-pack/functionbeat/docs/tab-widgets/deploy-aws.asciidoc new file mode 100644 index 00000000000..9118384d6e0 --- /dev/null +++ b/x-pack/functionbeat/docs/tab-widgets/deploy-aws.asciidoc @@ -0,0 +1,19 @@ +// tag::mac[] +["source","sh",subs="attributes"] +---- +./{beatname_lc} -v -e -d "*" deploy cloudwatch +---- +// end::mac[] + +// tag::linux[] +["source","sh",subs="attributes"] +---- +./{beatname_lc} -v -e -d "*" deploy cloudwatch +---- +// end::linux[] +// tag::win[] +["source","sh",subs="attributes"] +---- +.{backslash}{beatname_lc}.exe -v -e -d "*" deploy cloudwatch +---- +// end::win[] diff --git a/x-pack/functionbeat/docs/tab-widgets/deploy-google-widget.asciidoc b/x-pack/functionbeat/docs/tab-widgets/deploy-google-widget.asciidoc new file mode 100644 index 00000000000..b5728a56717 --- /dev/null +++ b/x-pack/functionbeat/docs/tab-widgets/deploy-google-widget.asciidoc @@ -0,0 +1,58 @@ +++++ +
+
+ + + +
+
+++++ + +include::deploy-google.asciidoc[tag=mac] + +++++ +
+ + +
+++++ diff --git a/x-pack/functionbeat/docs/tab-widgets/deploy-google.asciidoc b/x-pack/functionbeat/docs/tab-widgets/deploy-google.asciidoc new file mode 100644 index 00000000000..58b707eaee1 --- /dev/null +++ b/x-pack/functionbeat/docs/tab-widgets/deploy-google.asciidoc @@ -0,0 +1,19 @@ +// tag::mac[] +["source","sh",subs="attributes"] +---- +./{beatname_lc} -v -e -d "*" deploy storage +---- +// end::mac[] + +// tag::linux[] +["source","sh",subs="attributes"] +---- +./{beatname_lc} -v -e -d "*" deploy storage +---- +// end::linux[] +// tag::win[] +["source","sh",subs="attributes"] +---- +.{backslash}{beatname_lc}.exe -v -e -d "*" deploy storage +---- +// end::win[]