[id="{beatname_lc}-getting-started"] == Getting started with {beatname_uc} {beatname_uc} helps you monitor your servers and the services they host by collecting metrics from the operating system and services. include::../../libbeat/docs/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/docs/shared-download-and-install.asciidoc[] [[deb]] *deb:* ifeval::["{release-state}"=="unreleased"] Version {stack-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 {stack-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 {stack-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::[] [[docker]] *docker:* ifeval::["{release-state}"=="unreleased"] Version {stack-version} of {beatname_uc} has not yet been released. endif::[] ifeval::["{release-state}"!="unreleased"] ["source", "shell", subs="attributes"] ------------------------------------------------ docker pull {dockerimage} ------------------------------------------------ endif::[] [[win]] *win:* ifeval::["{release-state}"=="unreleased"] Version {stack-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/docs/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:* + ["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/docs/step-configure-output.asciidoc[] include::../../libbeat/docs/step-configure-kibana-endpoint.asciidoc[] include::../../libbeat/docs/step-configure-credentials.asciidoc[] include::../../libbeat/docs/step-test-config.asciidoc[] include::../../libbeat/docs/step-look-at-config.asciidoc[] [id="{beatname_lc}-template"] === Step 3: Load the index template in Elasticsearch :allplatforms: include::../../libbeat/docs/shared-template-load.asciidoc[] [[load-kibana-dashboards]] === Step 4: Set up the Kibana dashboards :allplatforms: include::../../libbeat/docs/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:* ["source","sh",subs="attributes"] ---------------------------------------------------------------------- sudo service {beatname_lc} start ---------------------------------------------------------------------- *rpm:* ["source","sh",subs="attributes"] ---------------------------------------------------------------------- sudo service {beatname_lc} start ---------------------------------------------------------------------- *docker:* See <>. *mac:* ["source","sh",subs="attributes,callouts"] ---------------------------------------------------------------------- sudo chown root {beatname_lc}.yml <1> sudo chown root modules.d/system.yml <1> sudo ./{beatname_lc} -e -c {beatname_lc}.yml -d "publish" ---------------------------------------------------------------------- <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 {libbeat}/config-file-permissions.html[Config File Ownership and Permissions] in the _Beats Platform Reference_. *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/docs/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]