Cleanup for PA enable and removal

Author: aetter

docs/install/deb.md

@@ -109,20 +109,22 @@ sudo /bin/systemctl enable elasticsearch.service
 
 You can also modify the values in `/etc/default/elasticsearch` (`JAVA_HOME`, most notably), `/etc/elasticsearch/elasticsearch.yml`, and `/etc/elasticsearch/jvm.options` (to set the heap size, most notably). To learn more, see [Elasticsearch configuration](../../elasticsearch/configuration/) and [Important Settings](../docker#important-settings) on the Docker page.
 
-### Setup Performance Analyzer
 
-By default, Performance Analyzer's endpoints will not be accessible from outside the host machine.
+### (Optional) Set up Performance Analyzer
 
-To edit this behavior you'll need to modify the plugin configuration. First navigate to your `ES_HOME` which is `/usr/share/elasticsearch` for a standard installation.
+By default, Performance Analyzer's endpoints are not accessible from outside the host machine.
+
+To edit this behavior, modify the plugin configuration. First navigate to `ES_HOME`, which is `/usr/share/elasticsearch` for a standard installation.
 
 ```bash
 cd $ES_HOME # navigate to the Elasticsearch home directory
 cd plugins/opendistro_performance_analyzer/pa_config/
 vi performance-analyzer.properties
 ```
 
-Uncomment the line `#webservice-bind-host` and set it to `0.0.0.0`. An example is provided below.
-```bash
+Uncomment the line `#webservice-bind-host` and set it to `0.0.0.0`:
+
+```
 # ======================== Elasticsearch performance analyzer plugin config =========================
 
 # NOTE: this is an example for Linux. Please modify the config accordingly if you are using it under other OS.
@@ -162,11 +164,13 @@ plugin-stats-metadata = plugin-stats-metadata
 agent-stats-metadata = agent-stats-metadata
 ```
 
-Finally, restart the Elasticsearch service and PerformanceAnalyzer will be accessible from outside the machine.
+Finally, restart the Elasticsearch service. After the restart, Performance Analyzer is accessible from outside the machine:
+
 ```bash
 sudo systemctl restart elasticsearch.service
 ```
 
+
 ## Where are the files?
 
 The Debian package installs files to the following locations:

docs/install/docker.md

@@ -187,49 +187,23 @@ services:
 You can use this same method to [pass your own certificates](../docker-security/) for use with the [Security](../../security/configuration/) plugin.
 
 
-## Bash access to containers
-
-To create an interactive Bash session in a container, run `docker ps` to find the container ID. Then run:
-
-```bash
-docker exec -it <container-id> /bin/bash
-```
-
+### (Optional) Set up Performance Analyzer
 
-## Important settings
+By default, Performance Analyzer's endpoints are not accessible from outside the Docker container.
 
-For production workloads, make sure the [Linux setting](https://www.kernel.org/doc/Documentation/sysctl/vm.txt) `vm.max_map_count` is set to at least 262144. On the Open Distro for Elasticsearch Docker image, this setting is the default. To verify, start a Bash session in the container and run:
+To edit this behavior, open a shell session in the container and modify the configuration:
 
 ```bash
-cat /proc/sys/vm/max_map_count
-```
-
-To increase this value, you have to modify the Docker image. On the RPM install, you can add this setting to the host machine's `/etc/sysctl.conf` file by adding the following line:
-
-```
-vm.max_map_count=262144
-```
-
-Then run `sudo sysctl -p` to reload.
-
-The `docker-compose.yml` file above also contains several key settings: `bootstrap.memory_lock=true`, `ES_JAVA_OPTS=-Xms512m -Xmx512m`, `nofile 65536` and `port 9600`. Respectively, these settings disable memory swapping (along with `memlock`), set the size of the Java heap (we recommend half of system RAM), set a limit of 65536 open files for the Elasticsearch user, and allow you to access Performance Analyzer on port 9600.
-
-### Setup Performance Analyzer
-
-By default, Performance Analyzer's endpoints will not be accessible from outside the Docker container.
-
-To edit this behavior you'll need to open up a shell session in the container and modify the configuration.
-
-```bash
-docker ps # Lookup the container id
+docker ps # Look up the container id
 docker exec -it <container-id> /bin/bash
 # Inside container
 cd plugins/opendistro_performance_analyzer/pa_config/
 vi performance-analyzer.properties
 ```
 
-Uncomment the line `#webservice-bind-host` and set it to `0.0.0.0`. An example is provided below.
-```bash
+Uncomment the line `#webservice-bind-host` and set it to `0.0.0.0`:
+
+```
 # ======================== Elasticsearch performance analyzer plugin config =========================
 
 # NOTE: this is an example for Linux. Please modify the config accordingly if you are using it under other OS.
@@ -269,10 +243,41 @@ plugin-stats-metadata = plugin-stats-metadata
 agent-stats-metadata = agent-stats-metadata
 ```
 
-Finally, restart the Performance Analyzer agent and it will become accessible.
+Then restart the Performance Analyzer agent:
+
 ```bash
 kill $(ps aux | grep -i 'PerformanceAnalyzerApp' | grep -v grep | awk '{print $2}')
 ```
+
+
+## Bash access to containers
+
+To create an interactive Bash session in a container, run `docker ps` to find the container ID. Then run:
+
+```bash
+docker exec -it <container-id> /bin/bash
+```
+
+
+## Important settings
+
+For production workloads, make sure the [Linux setting](https://www.kernel.org/doc/Documentation/sysctl/vm.txt) `vm.max_map_count` is set to at least 262144. On the Open Distro for Elasticsearch Docker image, this setting is the default. To verify, start a Bash session in the container and run:
+
+```bash
+cat /proc/sys/vm/max_map_count
+```
+
+To increase this value, you have to modify the Docker image. On the RPM install, you can add this setting to the host machine's `/etc/sysctl.conf` file by adding the following line:
+
+```
+vm.max_map_count=262144
+```
+
+Then run `sudo sysctl -p` to reload.
+
+The `docker-compose.yml` file above also contains several key settings: `bootstrap.memory_lock=true`, `ES_JAVA_OPTS=-Xms512m -Xmx512m`, `nofile 65536` and `port 9600`. Respectively, these settings disable memory swapping (along with `memlock`), set the size of the Java heap (we recommend half of system RAM), set a limit of 65536 open files for the Elasticsearch user, and allow you to access Performance Analyzer on port 9600.
+
+
 ## Customize the Docker image
 
 To run the image with a custom plugin, first create a [`Dockerfile`](https://docs.docker.com/engine/reference/builder/):

docs/install/plugins.md

@@ -264,64 +264,65 @@ Performance Analyzer requires some manual configuration after installing the plu
    sudo chmod +x /usr/share/elasticsearch/bin/performance-analyzer-agent-cli
    ```
 
-1. Run the appropriate postinst script for your Linux distro
+1. Run the appropriate `postinst` script for your Linux distribution:
 
-    ```bash
-   # DEB distros
+   ```bash
+   # Debian-based distros
    sudo sh /usr/share/elasticsearch/plugins/opendistro_performance_analyzer/install/deb/postinst.sh 1
-   
+
    # RPM distros
    sudo sh /usr/share/elasticsearch/plugins/opendistro_performance_analyzer/install/rpm/postinst.sh 1
-    ```
+   ```
 
 1. Make Performance Analyzer accessible outside of the host machine
 
-    ```bash
-    cd /usr/share/elasticsearch # navigate to the Elasticsearch home directory
-    cd plugins/opendistro_performance_analyzer/pa_config/
-    vi performance-analyzer.properties
-    ```
-    
-    Uncomment the line `#webservice-bind-host` and set it to `0.0.0.0`. An example is provided below.
-    ```bash
-    # ======================== Elasticsearch performance analyzer plugin config =========================
-    
-    # NOTE: this is an example for Linux. Please modify the config accordingly if you are using it under other OS.
-    
-    # WebService bind host; default to all interfaces
-    webservice-bind-host = 0.0.0.0
-    
-    # Metrics data location
-    metrics-location = /dev/shm/performanceanalyzer/
-    
-    # Metrics deletion interval (minutes) for metrics data.
-    # Interval should be between 1 to 60.
-    metrics-deletion-interval = 1
-    
-    # If set to true, the system cleans up the files behind it. So at any point, we should expect only 2
-    # metrics-db-file-prefix-path files. If set to false, no files are cleaned up. This can be useful, if you are archiving
-    # the files and wouldn't like for them to be cleaned up.
-    cleanup-metrics-db-files = true
-    
-    # WebService exposed by App's port
-    webservice-listener-port = 9600
-    
-    # Metric DB File Prefix Path location
-    metrics-db-file-prefix-path = /tmp/metricsdb_
-    
-    https-enabled = false
-    
-    #Setup the correct path for certificates
-    certificate-file-path = specify_path
-    
-    private-key-file-path = specify_path
-    
-    # Plugin Stats Metadata file name, expected to be in the same location
-    plugin-stats-metadata = plugin-stats-metadata
-    
-    # Agent Stats Metadata file name, expected to be in the same location
-    agent-stats-metadata = agent-stats-metadata
-    ```
+   ```bash
+   cd /usr/share/elasticsearch # navigate to the Elasticsearch home directory
+   cd plugins/opendistro_performance_analyzer/pa_config/
+   vi performance-analyzer.properties
+   ```
+
+   Uncomment the line `#webservice-bind-host` and set it to `0.0.0.0`:
+
+   ```bash
+   # ======================== Elasticsearch performance analyzer plugin config =========================
+
+   # NOTE: this is an example for Linux. Please modify the config accordingly if you are using it under other OS.
+
+   # WebService bind host; default to all interfaces
+   webservice-bind-host = 0.0.0.0
+
+   # Metrics data location
+   metrics-location = /dev/shm/performanceanalyzer/
+
+   # Metrics deletion interval (minutes) for metrics data.
+   # Interval should be between 1 to 60.
+   metrics-deletion-interval = 1
+
+   # If set to true, the system cleans up the files behind it. So at any point, we should expect only 2
+   # metrics-db-file-prefix-path files. If set to false, no files are cleaned up. This  can be useful, if you are archiving
+   # the files and wouldn't like for them to be cleaned up.
+   cleanup-metrics-db-files = true
+
+   # WebService exposed by App's port
+   webservice-listener-port = 9600
+
+   # Metric DB File Prefix Path location
+   metrics-db-file-prefix-path = /tmp/metricsdb_
+
+   https-enabled = false
+
+   #Setup the correct path for certificates
+   certificate-file-path = specify_path
+
+   private-key-file-path = specify_path
+
+   # Plugin Stats Metadata file name, expected to be in the same location
+   plugin-stats-metadata = plugin-stats-metadata
+
+   # Agent Stats Metadata file name, expected to be in the same location
+   agent-stats-metadata = agent-stats-metadata
+   ```
 
 1. Start the Elasticsearch service:
 
@@ -347,37 +348,41 @@ sudo bin/elasticsearch-plugin list
 
 ## Remove plugins
 
-### (Optional) Cleanup Performance Analyzer files
+If you are removing Performance Analyzer, see below.
+
+```bash
+sudo bin/elasticsearch-plugin remove <plugin-name>
+```
+
+Then restart Elasticsearch on the node.
+
+```bash
+sudo systemctl restart elasticsearch.service
+```
+
 
-Performance Analyzer relies on certain config files to run. If you want to delete these files, run one of the 
-scripts we've provided based on your Linux distribution
+### (Optional) Clean up Performance Analyzer files
 
-1. Make the removal scripts executable 
+Performance Analyzer requires certain configuration files to run. If you want to delete these files, run one of the scripts we provide based on your Linux distribution *before* performing the normal plugin removal process.
 
-    ```bash
-    sudo chmod +x plugins/opendistro_performance_analyer/install/deb/postrm sudo sh plugins/opendistro_performance_analyer/install/rpm/postrm
-    ```
+1. Make the removal scripts executable
 
-1. Run the appropriate removal script for your distribution
-    ```bash
-    # Debian distribution
-    sudo --preserve-env=ES_HOME ./plugins/opendistro_performance_analyer/install/deb/postrm
-    
-    # Redhat distribution
-    sudo --preserve-env=ES_HOME ./plugins/opendistro_performance_analyer/install/rpm/postrm
-    ```
+   ```bash
+   sudo chmod +x plugins/opendistro_performance_analyer/install/deb/postrm sudo sh plugins/opendistro_performance_analyer/install/rpm/postrm
+   ```
 
-1. Then you can proceed with the normal removal procedure.
+1. Run the appropriate removal script for your distribution:
 
-    ```bash
-    sudo bin/elasticsearch-plugin remove <plugin-name>
-    ```
+   ```bash
+   # Debian-based distros
+   sudo --preserve-env=ES_HOME ./plugins/opendistro_performance_analyer/install/deb/postrm
+
+   # RPM distros
+   sudo --preserve-env=ES_HOME ./plugins/opendistro_performance_analyer/install/rpm/postrm
+   ```
 
-1. Finally,  restart Elasticsearch on the node.
+Then proceed with the normal removal procedure.
 
-    ```bash
-    sudo systemctl restart elasticsearch.service
-    ```
 
 ## Update plugins
 

docs/install/rpm.md

@@ -99,20 +99,22 @@ sudo /bin/systemctl enable elasticsearch.service
 
 You can also modify the values in `/etc/sysconfig/elasticsearch` (`JAVA_HOME`, most notably), `/etc/elasticsearch/elasticsearch.yml`, and `/etc/elasticsearch/jvm.options` (to set the heap size, most notably). To learn more, see [Elasticsearch configuration](../../elasticsearch/configuration/) and [Important Settings](../docker#important-settings) on the Docker page.
 
-### Setup Performance Analyzer
 
-By default, Performance Analyzer's endpoints will not be accessible from outside the host machine.
+### (Optional) Set up Performance Analyzer
 
-To edit this behavior you'll need to modify the plugin configuration. First navigate to your `ES_HOME` which is `/usr/share/elasticsearch` for a standard installation.
+By default, Performance Analyzer's endpoints are not accessible from outside the host machine.
+
+To edit this behavior, modify the plugin configuration. First navigate to `ES_HOME`, which is `/usr/share/elasticsearch` for a standard installation.
 
 ```bash
 cd $ES_HOME # navigate to the Elasticsearch home directory
 cd plugins/opendistro_performance_analyzer/pa_config/
 vi performance-analyzer.properties
 ```
 
-Uncomment the line `#webservice-bind-host` and set it to `0.0.0.0`. An example is provided below.
-```bash
+Uncomment the line `#webservice-bind-host` and set it to `0.0.0.0`:
+
+```
 # ======================== Elasticsearch performance analyzer plugin config =========================
 
 # NOTE: this is an example for Linux. Please modify the config accordingly if you are using it under other OS.
@@ -152,7 +154,8 @@ plugin-stats-metadata = plugin-stats-metadata
 agent-stats-metadata = agent-stats-metadata
 ```
 
-Finally, restart the Elasticsearch service and PerformanceAnalyzer will be accessible from outside the machine.
+Finally, restart the Elasticsearch service. After the restart, Performance Analyzer is accessible from outside the machine:
+
 ```bash
 sudo systemctl restart elasticsearch.service
 ```