{"id":14063399,"url":"https://github.com/alvar-freude/Posemo","last_synced_at":"2025-07-29T15:32:57.733Z","repository":{"id":80124700,"uuid":"91689400","full_name":"alvar-freude/Posemo","owner":"alvar-freude","description":"PostgreSQL Secure Monitoring","archived":false,"fork":false,"pushed_at":"2019-09-28T00:53:27.000Z","size":1096,"stargazers_count":27,"open_issues_count":0,"forks_count":4,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-08-13T07:04:51.296Z","etag":null,"topics":["cpan","database","monitoring","perl","perl-modules","pgtap","posemo","postgres","postgresql","postgresql-extension","postgresql-monitoring"],"latest_commit_sha":null,"homepage":null,"language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"postgresql","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alvar-freude.png","metadata":{"files":{"readme":"README.md","changelog":"Changes","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-05-18T12:12:45.000Z","updated_at":"2024-01-19T10:24:39.000Z","dependencies_parsed_at":"2023-09-21T02:37:31.718Z","dependency_job_id":null,"html_url":"https://github.com/alvar-freude/Posemo","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alvar-freude%2FPosemo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alvar-freude%2FPosemo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alvar-freude%2FPosemo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alvar-freude%2FPosemo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alvar-freude","download_url":"https://codeload.github.com/alvar-freude/Posemo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228028371,"owners_count":17858324,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpan","database","monitoring","perl","perl-modules","pgtap","posemo","postgres","postgresql","postgresql-extension","postgresql-monitoring"],"created_at":"2024-08-13T07:03:19.335Z","updated_at":"2024-12-04T01:30:44.929Z","avatar_url":"https://github.com/alvar-freude.png","language":"Perl","funding_links":[],"categories":["Perl"],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/alvar-freude/Posemo.svg?branch=master)](https://travis-ci.org/alvar-freude/Posemo)\n\n# Posemo – PostgreSQL Secure Monitoring\n\nPosemo is a PostgreSQL monitoring framework, that can monitor everything in Postgres with an unprivileged user, which has no access to any data. Posemo conforms to the rules of the *German Federal Office for Information Security* ([Bundesamt für Sicherheit in der Informationstechnik](https://www.bsi.bund.de/), BSI). It is built to check tens, hundreds or thousands of servers fast.\n\nPosemo itself has no display capabilities, but can output the results for every monitoring environment (e.g. check_mk, Nagios, Zabbix, Icinga, …).\n\n## This is a Pre-Release!\n\nThis is now a **usable** pre-release with limited checks. It is not feature complete. **See quick installation instructions below.**\n\nPosemo is in active development, more checks are coming!\n\nPull requests are welcome, feature requests too.\n\nStarting with version 0.71, there is also a Debian package. See packages folder.\n\nStarting with version 0.72, Posemo can also run as daemon (via `posemo_daemon.pl`).\n\n## Synopsis / Examples\n\n  ```shell\n  # Installation:\n  # Install Posemo in local PostgreSQL\n  posemo_install.pl --create-database --create-schema\n\n  # Show all options, current and default values of installation programm\n  posemo_install.pl --show-options\n  \n  # Running:\n  # Start a simple run with default configs\n  posemo.pl \n\n  # Show all options, current and default values\n  posemo.pl --show-options\n\n  # Format output pretty\n  posemo.pl --pretty\n  \n  # The same, explizit JSON output\n  posemo.pl JSON --pretty\n  \n  # Output for CheckMK, instead plain JSON\n  posemo.pl CheckMK\n  \n  # Run with default output (JSON), given configfile and outfile\n  posemo.pl --configfile=conf/my-posemo-config.conf --outfile=results/posemo-test.json --pretty\n  \n  # Run checks and generate metrics file for Check_MK\n  # You may use \"=\" --option=value, or space: --option value\n  posemo.pl CheckMK posemo.pl CheckMK --metrics-outfile=/path/to/checkmk/metrics/posemo --outfile result.txt\n  \n  # Posemo as Daemon:\n  # Run as daemon in background, run all 60 seconds with outfile\n  posemo_daemon.pl --outfile=results/daemon-test.json\n  \n  # The same, explicit start command\n  posemo_daemon.pl start --outfile=results/daemon-test.json\n\n  # Daemon mode and CheckMK output\n  posemo_daemon.pl start CheckMK --outfile=results/daemon-test.checkmk\n  \n  # Start daemon und run checks every 5 seconds!\n  posemo_daemon.pl --outfile=results/daemon-test.json --sleep-time=5\n\n  # Check, if the daemon is running.\n  posemo_daemon.pl status\n  \n  # Stop daemon\n  posemo_daemon.pl stop\n  \n  # Daemon mode understands everything from App::Daemon\n  # e.g. set other PID file etc.\n  posemo_daemon.pl --outfile=tmp/result.json -p posemo.pid\n  \n  ```\n\n\n\n## HOWTOs and Manuals \n\n### User manuals\n\n* [Users Guide to the config file](pod/PostgreSQL/SecureMonitoring/Manual/UserConfig.pod)\n\n* TODO: Write Users guide for setup and running posemo ...\n\n\n### Developer manuals\n\n* [How to write Check Modules](pod/PostgreSQL/SecureMonitoring/Manual/CheckModules.pod)\n\n* [How to write a frontend connector / output modules](pod/PostgreSQL/SecureMonitoring/Manual/OutputModules.pod)\n\n* [Coding Styleguide](pod/PostgreSQL/SecureMonitoring/Manual/Styleguide.pod)\n\n\n\n## Concepts\n\nPosemo is a modular framework for creating monitoring checks for PostgreSQL. It is simple to add a new check. Usually you just have to write the SQL for the check and add some configuration. It is recommended to write some tests for every check.\n\nYou may look in [PostgreSQL::SecureMonitoring::Checks](lib/PostgreSQL/SecureMonitoring/Checks) for the checks currently ready to use.\n\nPosemo is a modern Perl application using Moose; at installation it generates PostgreSQL functions for every check. These functions are called by an unprivileged user who can only call these functions, nothing else. But since they are `SECURITY DEFINER` functions, they run with more privileges (usually as superuser, and since PostgreSQL 10 as a user, which is member of `pg_monitor`). You need a superuser for installation, but checks can run (from remote or local) by an unprivileged user. Therefore, **the monitoring server need no access to your databases, no access to PostgreSQL internals; it can't change or read your data – it can only call some predefined functions.**\n\n\nFor a simple check you may look below at the *SimpleAlive* Check, which simply returns always true. It uses a lot of defaults from `PostgreSQL::SecureMonitoring::Checks` and sugar from `PostgreSQL::SecureMonitoring::ChecksHelper`:\n\n```perl\npackage PostgreSQL::SecureMonitoring::Checks::SimpleAlive; # by Default, the name of the check is build from this package name\n\n\nuse PostgreSQL::SecureMonitoring::ChecksHelper;            # enables Moose, exports sugar functions; enables strict\u0026warnings\nextends \"PostgreSQL::SecureMonitoring::Checks\";            # We extend our base class ::Checks\n\ncheck_has code =\u003e \"SELECT true\";                           # This is our check SQL!\n\n1;                                                         # every Perl module must return (end with) a true value\n```\n\n(The real `Alive` check has more code, because it's the only one, which catches connection errors by itself.)\n\n\nA more advanced check is *BackupAge* check, which checks how long a backup is running and returns the seconds as integer:\n\n\n```perl\npackage PostgreSQL::SecureMonitoring::Checks::BackupAge;  # same as above ...\n\nuse PostgreSQL::SecureMonitoring::ChecksHelper;\nextends \"PostgreSQL::SecureMonitoring::Checks\";\n\ncheck_has                                                 # here more options and Code/SQL for the check\n   return_type =\u003e 'integer',\n   result_unit =\u003e 'seconds',\n   code        =\u003e \"SELECT CASE WHEN pg_is_in_backup()\n                               THEN CAST(extract(EPOCH FROM statement_timestamp() - pg_backup_start_time()) AS integer)\n                               ELSE NULL\n                               END\n                          AS backup_age;\";\n\n1;\n\n```\n\nFor a lot more examples see the [full documentation about writing modules](pod/PostgreSQL/SecureMonitoring/Manual/CheckModules.pod), the existing modules in [lib/PostgreSQL/SecureMonitoring/Checks](lib/PostgreSQL/SecureMonitoring/Checks) and the base class `PostgreSQL::SecureMonitoring::Checks` (in [lib/PostgreSQL/SecureMonitoring/Checks.pm](lib/PostgreSQL/SecureMonitoring/Checks.pm)).\n\n\n### PostgreSQL Roles\n\nPosemo needs two roles (users): one superuser as owner of all check functions (or beginning with PostgreSQL 10.0: a user, which is member of `pg_monitor`) and an unprivileged user, which only can call the check functions. You can create this users at installation time automatically or manually by yourself. Each role should have the most least privileges.\n\n\n## Installation\n\nPosemo is written in modern Perl and is tested with 5.16 and up, but should also work with ancient versions down to 5.10. It needs some Perl modules as dependencies. Currently it is not available on CPAN or as package, so it doesn't install all dependencies automatically.\n\n* Perl is usually installed by your OS. Some Linux distributions deliver broken Perl packages and maybe you should install the perl default modules `perl-modules`.\n* If you don't want to (or can't) install all dependencies with the package manager of your OS, it may be better to install your own Perl to avoid conflicts with system packages. The best way is to use [perlbrew](http://perlbrew.pl) for this. The latest Perl without ithreads is fine.\n* Posemo is not tested on Windows, but should work with [Strawberry Perl](http://strawberryperl.com)\n\n\n### Perl modules\n\nThe following instructions assume, that you have a fresh perlbrew Perl installed, which is recommended at least for development. (A list of Debian/Ubuntu packages is in the file Build.PL at the end, this should work.)\n\nYou find a list of all dependencies in Build.PL.\n\nPosemo uses `Module::Build` for building and testing. This is not included anymore in newer Perl versions, so you have to install it manually:\n\n```\n$ cpan Module::Build\n```\n\nPull the latest version of Posemo and install all dependencies:\n\n\n```\nperl Build.PL               # generate Build script\n./Build prereq_report       # (optionally) show depencencies\n./Build installdeps         # install all depencencies\n```\n\nSometimes some CPAN modules install/test not correctly; then you may run installdeps multiple times or install missing modules manually:\n\n```\ncpan Missing::ModuleName\n```\n\nWhen all dependencies are installed, you may start the tests, see below.\n\n\n## Running Posemo Checks\n\nBefore running Posemo, all the check functions must be installed in a database. It is also recommended to use an own user and superuser only for the checks. The Posemo installer does everything. To install all checks with `posemo_install.pl` on the local host:\n\n```\n$ bin/posemo_install.pl --create_database --create_superuser --create_user\nINFO : Install Posemo and Checks\nINFO : INSTALL: create monitoring database 'monitoring'\nINFO : INSTALL: create monitoring superuser 'monitoring_admin'\nINFO : INSTALL: create monitoring user 'monitoring'\nINFO : Install all check functions\nINFO : Install all checks\nINFO :   =\u003e Check Activity\nINFO :   =\u003e Check Alive\nINFO :   =\u003e Check BackupAge\nINFO :   =\u003e Check Writeable\nINFO : Posemo installed.\n```\n\nYou can see all options with a short description via `--help` (Short: `-h`) or with default values via `--show_options`.\n\nNow you can run the checks with `posemo.pl`:\n\n```\n$ bin/posemo.pl --pretty --outfile=monitoring-result.json\nINFO : Run check Activity for host localhost\nINFO : Run check Alive for host localhost\nINFO : Run check Backup Age for host localhost\nINFO : Run check Writeable for host localhost\n```\n\nYou can see all options with a short description via `--help` (Short: `-h`) or with default values via `--show_options`.\n\nThe result is now in the outfile; if no outfile is given, then output goes to STDOUT. Messages (INFO, …) go to STDERR, so you can redirect them both.\n\nFor more complex configuration look into the examples in `conf/` or the tests in `t/`.\n\n\n\n## Test Driven Development\n\nFor development, you usually don't run the real checks, but the test environment. It installs everything in a clean temporary PostgreSQL database (test files `t/[01]*`) and cleans it up after testing (test files `t/99*`).\n\nFor testing you need a local PostgreSQL installation. We use a new testing module for starting/stopping/... PostgreSQL instances called `Test::PostgreSQL::Starter`, which is included (but will be a separate CPAN module later).\n\nThe [pgTAP PostgreSQL extension](http://pgtap.org) ([pgTAP code on GitHub](https://github.com/theory/pgtap/)) is necessary too (installed in the local Postgres-Installation).\n\nTo start all the tests run:\n\n```\n./Build test               # at first time, you need to run perl Build.PL first\n```\n\nDevelopers should set the environment variable `TEST_AUTHOR` to a true value.\n\nYou may want run only some tests:\n\n```\n./Build test test_files=t/[01]*       verbose=1   # install test server, verbose output\n./Build test test_files=t/501-alive.* verbose=1   # runs tests of the alive check\n./Build test test_files=t/99*         verbose=1   # stop test server\n```\n\n\n\n##  Author\n\nPosemo is written by [Alvar C.H. Freude](https://alvar.a-blast.org/), 2016–2018.\n\nalvar@a-blast.org\n\nContributions are welcome!\n\n## License\n\nPosemo is released under the [PostgreSQL License](https://opensource.org/licenses/postgresql), a liberal Open Source license, similar to the BSD or MIT licenses.\n\nSee LICENSE.txt\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falvar-freude%2FPosemo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falvar-freude%2FPosemo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falvar-freude%2FPosemo/lists"}