ELK Installation Guide - tsgrp/HPI GitHub Wiki

For installation on a local machine or a single server, follow the instructions for ELK Stack Installation straight through. Ignore the Filebeat Installation.

If installing ELK on a separate server from the tomcat, begin with the ELK Stack Installation instructions on the ELK Server. After completing the Startup section, follow the steps in Filebeat Installation before continuing on to Index Setup and Importing Visualizations.

All v6.7.0 installers can be found on the TSG Snapserver in the ELK folder.

ELK Stack Installation

Deployment

  1. Create a folder called "ELK" in the D drive
  2. Elasticsearch
    1. Create a new folder in D:\ELK called "Elasticsearch"
    2. Extract the Elasticsearch.zip installer to D:\ELK\Elasticsearch
  3. Logstash
    1. Create a new folder in D:\ELK called "Logstash"
    2. Extract the Logstash.zip installer to D:\ELK\Logstash
  4. Kibana
    1. Create a new folder in D:\ELK called "Kibana"
    2. Extract the Kibana.zip installer to D:\ELK\Kibana

Installing ELK as a Windows Service

Reference: https://logz.io/blog/installing-the-elk-stack-on-windows/

  1. Elasticsearch
    1. Open a command prompt in {ELASTICSEARCH_HOME}\bin
    2. Run elasticsearch-service install. You should see "The service 'elasticsearch-service-x64' has been installed."
    3. Run elasticsearch-service.bat manager. A window should pop up
    4. Set the following properties under the General tab:
      • Display name: Elasticsearch
      • Startup: Manual
    5. Confirm installation by refreshing Services. You should see the newly installed Elasticsearch service
  2. Logstash
    1. In order to install Logstash and Kibana as a service, you need to use the Non-Sucking Service Manager (NSSM). Extract the nssm.zip installer to D:\nssm
    2. Open a command prompt in D:\nssm\win64
    3. Run nssm install Logstash. The installer should pop up
    4. Set the following properties:
      1. Application tab:
        • Path: {LOGSTASH_HOME}\bin\logstash.bat
        • Startup directory: {LOGSTASH_HOME}\bin
        • Arguments: -f {LOGSTASH_HOME}\bin\logstash.conf
        • Service name: Logstash
      2. Details tab:
        • Startup type: Manual
    5. Click Install Service. You should see a new popup that says "Service 'Logstash' installed successfully!" Click OK.
    6. Confirm installation by refreshing Services. You should see the newly installed Logstash service
    7. Copy the logstash.conf file from {OCMS_HOME}\setup\ELK and put it in {LOGSTASH_HOME}\bin, replacing the file if it already exists
    8. Open logstash.conf and replace the input file path value with the path to the oc-performance logs on your tomcat (ie. {ALFRESCO_HOME}/oc-performance*)
    9. Create a patterns folder in {LOGSTASH_HOME} if it doesn't already exist
    10. Copy the customPatterns.txt file from {OCMS_HOME}\setup\ELK and place it in {LOGSTASH_HOME}\patterns, replacing the file if it already exists
  3. Kibana
    1. In the same D:\nssm\win64 command prompt used for Logstash, run nssm install Kibana. The installer should pop up
    2. Set the following properties:
      1. Application tab:
        • Path: {KIBANA_HOME}\bin\kibana.bat
        • Startup directory: {KIBANA_HOME}\bin
        • Arguments: leave blank
        • Service name: Kibana
      2. Details tab:
        • Startup type: Manual
    3. Click Install Service. You should see a new popup that says "Service 'Kibana' installed successfully!" Click OK.
    4. Confirm installation by refreshing Services. You should see the newly installed Kibana service
    5. If you want Kibana to be accessible by a host name besides localhost, open {KIBANA_HOME}\config\kibana.yml and change the server.host

Startup

When starting up the services, always start Elasticsearch first, then Logstash, then Kibana.

  1. Start up the Elasticsearch service. To confirm that it has finished starting up correctly, go to localhost:9200. You should see an Elasticsearch json
  2. Start up the Logstash service. To confirm that it has finished starting up correctly, go to localhost:9600. You should see a Logstash json
  3. Start up the Kibana service. Go to localhost:5601 and Kibana should load

At this point, if you have installed ELK on a separate server from your tomcat, go through the Filebeat Installation instructions before continuing.

Creating Index Patterns, Visualizations, and Dashboards

  1. Create a Kibana Index Pattern
    1. In Kibana, click on the Management tab. Under the Kibana menu to the right of the main menu, select Index Patterns
    2. Click on Create index pattern
    3. Enter logstash-stats* as the pattern
    4. Select log_server_timestamp as the Time Filter field name
  2. Import existing visualizations and dashboards
    1. In Kibana, go to Management -> Kibana -> Saved Objects
    2. Choose Import in the top right corner
    3. Import the KibanaConfigs.json file from {OCMS_HOME}\setup\ELK. This will import all the trunk dashboards and visualizations that already exist

See Visualizing Logs in Kibana for instructions on creating more Visualizations

Filebeat Installation

Reference: https://www.elastic.co/guide/en/beats/filebeat/5.0/filebeat-getting-started.html

Deploying and Installing Filebeat

  1. Create a folder called "Filebeat" in the D drive of the tomcat server and extract Filebeat.zip here
  2. Open a PowerShell as Administrator in {FILEBEAT_HOME}
  3. Run PowerShell.exe -ExecutionPolicy UnRestricted -File .\install-service-filebeat.ps1
  4. Open {FILEBEAT_HOME}\filebeat.yml
    1. Under inputs -> paths, list {ALFRESCO_HOME}\oc-performance* to pull logs from all the oc-performance logs
    2. Under output.logstash -> hosts, list "{IP_ADDRESS_OF_ELK_SERVER}:5044"
    3. Make sure the output.elasticsearch section has been commented out (we are going through Logstash, not straight to Elasticsearch)
  5. Back in {LOGSTASH_HOME}\bin\logstash.conf on the ELK server, replace the input file section with
beats {
	port => 5044
}

Restart Logstash and Kibana to register the change. 6. In the PowerShell as Admin in {FILEBEAT_HOME} from earlier, run Invoke-WebRequest -Method Put -InFile filebeat.template.json -Uri http://{ELK_SERVER}:9200/_template/filebeat?pretty. Be sure to update the host name of the ELK server. Elasticsearch MUST be running during this step 7. Start the Filebeat service. The logs should now be visible in the Kibana Discover tab

Applying an Index Lifecycle Policy

To apply an index lifecycle policy to the ELK setup, replace the output section of {LOGSTASH_HOME}\bin\logstash.conf where an index is specified with

output {
	elasticsearch {
		ilm_enabled => true
		ilm_rollover_alias => "logstash-stats"
		ilm_pattern => "000001"
		ilm_policy => "apm_policy"
	}
}

This will create indices with the name logstash-stats-###### using the policy apm_policy. This is still compatible with the Kibana logstash-stats* index pattern. See instructions for creating an Index Lifecycle Policy.