From 74386f3ffabcd7c784edffa410a2a147edbeeb64 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20Mo=CC=88ding?= Date: Wed, 3 Jul 2024 11:15:44 +0200 Subject: [PATCH] Update README --- README.md | 68 +++++++++++++++++++++++++++---------------------------- 1 file changed, 33 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 18e4e76..20a817b 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,22 @@ # Puppet Server Metrics -This Python3 script uses the [Puppet Server V2 metrics API](https://www.puppet.com/docs/puppet/8/server/metrics-api/v2/metrics_api.html) to show some performance metrics of the Puppetserver. The curses library is used to present the metrics with simple terminal graphics. +This Python3 script uses the [Puppet Server V2 metrics API](https://www.puppet.com/docs/puppet/8/server/metrics-api/v2/metrics_api.html) to repeatedly show performance metrics of your Puppetserver. The curses library is used to present the metrics using ASCII graphics in a terminal window. -![Screenshot](Screenshot.png) +This script might be useful for consultants visiting a Customer to investigate suspected performance problems with the Puppetserver. It only needs a default Python interpreter and provides graphical monitoring without any additional software installation. But it can of course be used by every other puppeteer as well. See the following screenshot for an example output. -This script might be useful for consultants visiting a Customer to investigate suspected performance problems with the Puppetserver. It only needs a default Python interpreter and provides graphical monitoring without any additional software installation. +![Screenshot](Screenshot.png) -If the appearance of the output looks familiar to you, then you are probably old enough to have worked with the VAX/VMS respectively OpenVMS operating system: the layout and implementation of the metric panels has been inspired by the `MONITOR SYSTEM` command. +*Fun Fact*: If the appearance of the output 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. - -### 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 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. -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" -}, -``` +### Running the script as root -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. +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 @@ -50,11 +27,11 @@ $ 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 define that here. But then you will have to rename the generated files as described below. +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 as shown (my username is `stm`): +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 @@ -73,8 +50,29 @@ The script will use your username to access the files so if you used a different Now you are set to run the script using your personal account. -### Running the script as root +### 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. -Running the script as `root` is also possible. The certificate issued for the Puppet Agent will be used if that is available and readable by the current user (e.g. by running the script as user `puppet` or `root`). +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: -## Usage +``` 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.