{"id":21351808,"url":"https://github.com/serverfarmer/heartbeat-server","last_synced_at":"2025-08-24T00:19:08.003Z","repository":{"id":92623428,"uuid":"117426467","full_name":"serverfarmer/heartbeat-server","owner":"serverfarmer","description":"Heartbeat server reference implementation, for shared hosting environments","archived":false,"fork":false,"pushed_at":"2018-10-27T21:59:01.000Z","size":7,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-22T17:13:32.475Z","etag":null,"topics":["alerting","cacti","heartbeat","icinga","monitoring","monitoring-server","nagios","pingdom","prtg","server-monitoring","statuscake","uptime","uptimerobot"],"latest_commit_sha":null,"homepage":"http://serverfarmer.org/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/serverfarmer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-14T12:03:24.000Z","updated_at":"2023-05-12T16:49:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"6e205223-2954-4cb8-aa62-cc74b5ce268c","html_url":"https://github.com/serverfarmer/heartbeat-server","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serverfarmer%2Fheartbeat-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serverfarmer%2Fheartbeat-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serverfarmer%2Fheartbeat-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serverfarmer%2Fheartbeat-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/serverfarmer","download_url":"https://codeload.github.com/serverfarmer/heartbeat-server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243826783,"owners_count":20354220,"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":["alerting","cacti","heartbeat","icinga","monitoring","monitoring-server","nagios","pingdom","prtg","server-monitoring","statuscake","uptime","uptimerobot"],"created_at":"2024-11-22T03:11:19.315Z","updated_at":"2025-03-16T04:41:19.522Z","avatar_url":"https://github.com/serverfarmer.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Overview\n\nHeartbeat is a Server Farmer subproject, that extends functionally of your existing monitoring/alerting solution by providing abilities to monitor network services, Docker containers, virtual machines, condition of hard drives and many other aspects of a Linux server.\n\nHeartbeat is divided into [client](https://github.com/serverfarmer/heartbeat-linux) and server parts. Client part is responsible for collecting data and sending reports every 2 minutes to server. Server part is responsible for storing information about each reported service and responding to queries from your monitoring/alerting solution, if this particular service is (still) alive or not.\n\nHeartbeat can work with any monitoring/alerting system, that supports http(s) keyword monitoring, including:\n- public: StatusCake, Uptimerobot, Pingdom etc.\n- local: Nagios, Icinga, Zabbix, PRTG etc.\n\n\n## Installation\n\nClient part is either installed manually or automatically by Server Farmer  - installation process is described in [heartbeat-linux repository](https://github.com/serverfarmer/heartbeat-linux).\n\nServer part is installed on webserver with PHP support. Version provided in this repository (the whole `heartbeat` subdirectory) can be just put into htdocs directory. It doesn't require memcached or any other dependencies, instead is uses `files` subdirectory to store temporary files - to ensure high performance, you should put this subdirectory name into `/etc/fstab` file, eg.:\n\n`tmpfs /var/www/html/heartbeat/files tmpfs noatime,size=512m 0 0`\n\nthen mount it (by executing `mount /var/www/html/heartbeat/files`) and put into vhost configuration:\n\n```\n\u003cDirectory /var/www/html/heartbeat/files\u003e\n    Order deny,allow\n    Deny from all\n\u003c/Directory\u003e\n```\n\n**If you don't care about high performance, or SSD drives health, you can skip fstab/vhost configuration** - just copying `heartbeat` subdirectory to your hosting directory is perfectly enough to make it work.\n\n\n## How it works\n\nServer part receives 2 types of requests:\n\n- reports from monitored hosts (handled by `index.php` file), containing the hostname and a list of detected services - such reports are send by each host every 2 minutes and reported services are considered alive for 270 seconds since last report (you can adjust this time, also per service name)\n- queries from monitoring/alerting solution (handled by `query.php` file), separately for each monitored host and service - and replies with either `ALIVE` or `DEAD` keyword\n\nSo, Heartbeat server is in fact just a kind of dumb proxy between monitored servers and your monitoring/alerting solution. All checks, as well as related logic (eg. list of notified people for each check) should be created directly in your monitoring/alerting solution (which does not even need to be accessible from monitored servers).\n\n\n## Query URL format\n\nAssuming that:\n- your Heartbeat server has address `http://heartbeat.yourdomain.com/heartbeat/`\n- your example monitored host has hostname `yourserver.yourdomain.com`\n\nthis is the complete URL that checks for `ssh` service running on this host:\n\n`http://heartbeat.yourdomain.com/heartbeat/query.php?id=ssh_yourserver_yourdomain_com`\n\nRules:\n- everything is converted to lowercase\n- underlines, colons and slashes are replaced with dashes\n- dots in hostnames are replaced with underlines\n- network service names are listed in `/opt/heartbeat/scripts/checks/services.sh` script\n\n\n## Performance\n\nSingle AWS `t2.micro` instance, storing temporary files on `tmpfs` filesystem, can handle over 3000 individual checks without any performance issues, assuming that queries from monitoring system are done via http (no encryption), every 1 minute.\n\nNote that you can use different addresses for reporting data from monitored hosts, and for querying (in particular, you can use https for reporting and http for querying over internal network).\n\n\n## Compatibility\n\nHeartbeat server requires PHP 5.2 or later, and is 100% compatible with PHP 7.x. It doesn't have any dependencies (eg. memcached, Redis, specific libraries or frameworks), however for maximum performance, `files` subdirectory should be mounted as `tmpfs` (see Installation section above).\n\n\n## How to contribute\n\nWe are welcome to contributions of any kind: bug fixes, versions for\ndifferent environments, using particular caching services etc.\n\nIf you want to contribute:\n- fork this repository and clone it to your machine\n- create a feature branch and do the change inside it\n- push your feature branch to github and create a pull request\n\n\n## License\n\n|                      |                                          |\n|:---------------------|:-----------------------------------------|\n| **Author:**          | Tomasz Klim (\u003copensource@tomaszklim.pl\u003e) |\n| **Copyright:**       | Copyright 2017-2018 Tomasz Klim          |\n| **License:**         | MIT                                      |\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserverfarmer%2Fheartbeat-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fserverfarmer%2Fheartbeat-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserverfarmer%2Fheartbeat-server/lists"}