Split documentation

smoeding · Jul 6, 2024 · 9cfd719 · 9cfd719
1 parent 2038f3d
commit 9cfd719
Show file tree

Hide file tree

Showing 3 changed files with 73 additions and 66 deletions.
diff --git a/INSTALL.md b/INSTALL.md
@@ -0,0 +1,68 @@
+# Installation and configuration
+
+The script requires a modern Python 3.x interpreter. All required modules are part of the Python core and no additional packages need to be installed.
+
+The Puppetserver API uses a client certificate for authentication. So the script will need access to a certificate issued by the Puppetserver to run. There are two ways this can be achieved. Running the script as root is simpler while running as ordinary user is more secure.
+
+## Running the script as root
+
+Running the script as `root` is possible. The certificate issued for the Puppet Agent will be used if that is available and readable by the current user. This might be the easiest way to quickly test the script.
+
+## Running the script as ordinary user
+
+If you plan to use the script as ordinary user, then you will have to create a new client certificate and have it signed by the Puppetserver. You can create a personal certification request by running the following two command:
+
+``` shell
+$ mkdir -p ~/.puppetlabs/opt/puppet/cache/devices
+$ puppet ssl bootstrap --verbose --server puppet.example.com --waitforcert 600 --target $USER
+```
+
+Obviously you will need to replace `puppet.example.com` with the name of your Puppetserver. The environment variable `$USER` is used to define the name of the certificate. If you like to use a different name, you can set that here instead. But then you will have to rename the generated files as described below.
+
+The command will wait for 10 minutes until the certificate signing request is signed.
+
+The next step will have to be performed as `root` on the Puppetserver. Your personal certificate signing request should be show when running the `puppetserver ca list` command. You must sign the request using the name given in the `puppet ssl bootstrap` command (my username is `stm`):
+
+``` shell
+# puppetserver ca list
+# puppetserver ca sign --certname stm
+```
+
+After that the initial command should complete and generate the required files. The key and certificate will be named using the target provided in the first command so in my case I get the following files:
+
+```
+/home/stm/.puppetlabs/etc/puppet/ssl/certs/ca.pem
+/home/stm/.puppetlabs/etc/puppet/ssl/certs/stm.pem
+/home/stm/.puppetlabs/etc/puppet/ssl/private_keys/stm.pem
+```
+
+The script will use your username to access the files so if you used a different target name in the first command, you will have to rename the generated files to match the names here (replace `stm` with your username).
+
+Now you are set to run the script using your personal account.
+
+## Prepare the Puppetserver
+
+The API endpoint is normally disabled. Use the following steps to enable it.
+
+Locate the authentication configuration of your Puppetserver. For Linux this should be the file `/etc/puppetlabs/puppetserver/conf.d/auth.conf`. Make a backup copy of this file in case you need to revert to the old configuration.
+
+The file uses the HOCON format, which is a superset of [JSON](https://en.wikipedia.org/wiki/JSON). It contains an array of objects that describe the access rules for the server.
+
+The last rule should have the name `puppetlabs deny all` that blocks all requests not allowed by the preceding rules. Add the following block just before the last block:
+
+``` hocon
+{
+    match-request: {
+        path: "/metrics/v2"
+        type: path
+        method: [get, post]
+    }
+    allow: "*"
+    sort-order: 500
+    name: "puppet metrics information"
+},
+```
+
+Take care to keep the braces balanced. Also note the trailing comma after the closing brace since this object is part of the rule array and the final array element should be the deny rule.
+
+Save the file and restart the Puppetserver. Check for errors in the Puppetserver log file in case of startup failures.
diff --git a/README.md b/README.md
@@ -24,75 +24,14 @@ optional arguments:
   --no-proxy           ignore proxy environment variables
 ```
 
-Details about the output and some tuning hints are given in the additional [TUNING](TUNING.md) reference.
+Normally the screen is updated every three seconds. You can set a different refresh rate using the `--interval` parameter.
 
 *Fun Fact*: If the appearance of the graphics looks familiar to you, then you are probably old enough to have worked with the VAX/VMS respectively OpenVMS operating system: the layout of the metric panels has been inspired by the VMS `MONITOR SYSTEM` utility.
 
 ## Installation and configuration
 
-The script requires a modern Python 3.x interpreter. All required modules are part of the Python core and no additional packages need to be installed.
-
-The Puppetserver API uses a client certificate for authentication. So the script will need access to a certificate issued by the Puppetserver to run. There are two ways this can be achieved. Running the script as root is simpler while running as ordinary user is more secure.
-
-### Running the script as root
-
-Running the script as `root` is possible. The certificate issued for the Puppet Agent will be used if that is available and readable by the current user. This might be the easiest way to quickly test the script.
-
-### Running the script as ordinary user
-
-If you plan to use the script as ordinary user, then you will have to create a new client certificate and have it signed by the Puppetserver. You can create a personal certification request by running the following two command:
-
-``` shell
-$ mkdir -p ~/.puppetlabs/opt/puppet/cache/devices
-$ puppet ssl bootstrap --verbose --server puppet.example.com --waitforcert 600 --target $USER
-```
-
-Obviously you will need to replace `puppet.example.com` with the name of your Puppetserver. The environment variable `$USER` is used to define the name of the certificate. If you like to use a different name, you can set that here instead. But then you will have to rename the generated files as described below.
+See the separate [INSTALL](INSTALL.md) document.
 
-The command will wait for 10 minutes until the certificate signing request is signed.
+## Tuning
 
-The next step will have to be performed as `root` on the Puppetserver. Your personal certificate signing request should be show when running the `puppetserver ca list` command. You must sign the request using the name given in the `puppet ssl bootstrap` command (my username is `stm`):
-
-``` shell
-# puppetserver ca list
-# puppetserver ca sign --certname stm
-```
-
-After that the initial command should complete and generate the required files. The key and certificate will be named using the target provided in the first command so in my case I get the following files:
-
-```
-/home/stm/.puppetlabs/etc/puppet/ssl/certs/ca.pem
-/home/stm/.puppetlabs/etc/puppet/ssl/certs/stm.pem
-/home/stm/.puppetlabs/etc/puppet/ssl/private_keys/stm.pem
-```
-
-The script will use your username to access the files so if you used a different target name in the first command, you will have to rename the generated files to match the names here (replace `stm` with your username).
-
-Now you are set to run the script using your personal account.
-
-### Prepare the Puppetserver
-
-The API endpoint is normally disabled. Use the following steps to enable it.
-
-Locate the authentication configuration of your Puppetserver. For Linux this should be the file `/etc/puppetlabs/puppetserver/conf.d/auth.conf`. Make a backup copy of this file in case you need to revert to the old configuration.
-
-The file uses the HOCON format, which is a superset of [JSON](https://en.wikipedia.org/wiki/JSON). It contains an array of objects that describe the access rules for the server.
-
-The last rule should have the name `puppetlabs deny all` that blocks all requests not allowed by the preceding rules. Add the following block just before the last block:
-
-``` hocon
-{
-    match-request: {
-        path: "/metrics/v2"
-        type: path
-        method: [get, post]
-    }
-    allow: "*"
-    sort-order: 500
-    name: "puppet metrics information"
-},
-```
-
-Take care to keep the braces balanced. Also note the trailing comma after the closing brace since this object is part of the rule array and the final array element should be the deny rule.
-
-Save the file and restart the Puppetserver. Check for errors in the Puppetserver log file in case of startup failures.
+Details about the output and some tuning hints are given in the additional [TUNING](TUNING.md) reference.
diff --git a/TUNING.md b/TUNING.md
@@ -71,6 +71,6 @@ In the example the mean number of allocated JRubies is 4.67 while at the specifi
 
 The bottom right panel shows the mean service time (in queueing theory traditionally written as $1/\mu$) for a JRuby in the upper graph. This is the mean time that the JRuby is allocated from the pool and is running the Ruby code to fulfil a request. The lower graph in the panel contains the mean wait time ($W_q$) that new requests will have to wait before a JRuby is available to start processing the request.
 
-Both times are presented in milliseconds. So for the given example we have a mean service time of 145.1ms and a mean wait time of 117.8ms. Waiting time is always a bad sign but in this case the wait time has the same magnitude as the service time so performance will suffer significantly.
+Both times are presented in milliseconds. So for the given example we have a mean service time of 145.1ms and a mean wait time of 117.8ms. Waiting time is always a bad sign but in this case the wait time has the same magnitude as the service time so here performance will suffer significantly.
 
 These measurements match the data from the usage graph as most of the time there doesn't seem to be a free JRuby in the pool to handle a new request when it arrives.