{"id":49157439,"url":"https://github.com/theoneoh1/blackbox-lite","last_synced_at":"2026-04-22T10:01:54.344Z","repository":{"id":322946045,"uuid":"1090796543","full_name":"TheOneOh1/blackbox-lite","owner":"TheOneOh1","description":"Bash script to monitor websites and VM hosts, exporting Prometheus metrics for Node Exporter.","archived":false,"fork":false,"pushed_at":"2025-11-07T06:25:50.000Z","size":229,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-07T08:21:48.934Z","etag":null,"topics":["bash","devops","infrastructure-monitoring","monitoring","node-exporter","prometheus","shell-script","synthetic-monitoring","textfile-collector"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TheOneOh1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-06T06:34:33.000Z","updated_at":"2025-11-07T06:46:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/TheOneOh1/blackbox-lite","commit_stats":null,"previous_names":["theoneoh1/blackbox-lite"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/TheOneOh1/blackbox-lite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheOneOh1%2Fblackbox-lite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheOneOh1%2Fblackbox-lite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheOneOh1%2Fblackbox-lite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheOneOh1%2Fblackbox-lite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheOneOh1","download_url":"https://codeload.github.com/TheOneOh1/blackbox-lite/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheOneOh1%2Fblackbox-lite/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32130776,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T08:34:57.708Z","status":"ssl_error","status_checked_at":"2026-04-22T08:34:55.583Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["bash","devops","infrastructure-monitoring","monitoring","node-exporter","prometheus","shell-script","synthetic-monitoring","textfile-collector"],"created_at":"2026-04-22T10:01:53.580Z","updated_at":"2026-04-22T10:01:54.339Z","avatar_url":"https://github.com/TheOneOh1.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\n# Blackbox Lite\n\n\nA comprehensive Bash script that monitors websites and VM hosts, collecting metrics in Prometheus format for integration with Node Exporter's textfile collector. It can also run as a **standalone CLI health checker** without any Prometheus setup. This tool provides real-time monitoring of website availability, SSL certificate health, response times, and VM host connectivity.\n\n## Features\n\n### Website Monitoring\n\n- **Availability Check**: Monitors website uptime with HTTP status code validation\n- **Response Time**: Measures website response time in seconds\n- **SSL Certificate Monitoring**:\n\t- Validates SSL certificate validity\n\t- Tracks days until certificate expiration\n\t- Detects TLS version in use\n- **HTTP Status Codes**: Captures and reports HTTP response codes\n- **Follow Redirects**: Automatically follows HTTP redirects (3xx)\n\n### VM Host Monitoring\n\n- **Ping Connectivity**: Tests host reachability using ICMP ping\n- **Response Time**: Measures average ping response time\n\n### Additional Features\n- **YAML Configuration**: External config file support - no script edits needed to add/remove targets\n- **Parallel Execution**: All checks run concurrently with configurable job limits\n- **CLI-Only Mode**: Use `--cli` for quick health checks without Prometheus - no textfile collector required\n- **Prometheus-Compatible**: Outputs metrics in standard Prometheus textfile format\n- **Atomic Writes**: Uses temporary files for safe metric updates\n- **Error Handling**: Strict mode (`set -Eeuo pipefail`), error traps, and dependency checking\n- **Metadata Metrics**: Includes monitoring run timestamps and target counts\n\n### Required Dependencies\n\nThe script automatically checks for and requires the following tools:\n\n- **curl**: For HTTP/HTTPS website checks\n- **openssl**: For SSL certificate validation and TLS version detection\n- **ping**: For VM host connectivity testing\n- **bc**: For mathematical calculations (response time conversions)\n\n\n## Configuration\n\n### Option 1: YAML Config File (Recommended)\n\nCreate a `config.yaml` alongside the script:\n\n```yaml\n# Path where Prometheus metrics are written\ntextfile_path: \"/opt/node_exporter/textfile_collector/combined_monitor.prom\"\n\n# Websites to monitor\nwebsites:\n  - \"https://example.com\"\n  - \"https://api.example.com/health\"\n  - \"http://internal.example.com:8080\"\n\n# VM hosts to monitor\nvm_hosts:\n  - \"server1.example.com\"\n  - \"192.168.1.100\"\n\n# Parallel execution settings\nparallel:\n  max_jobs: 5\n```\n\nThen run with:\n```bash\n./monitor.sh --config config.yaml\n```\n\n### Option 2: Hardcoded Defaults (Fallback)\n\nIf no `--config` flag is provided, the script uses the built-in arrays as a fallback. Edit the `DEFAULT_WEBSITES` and `DEFAULT_VM_HOSTS` arrays directly in the script:\n\n```bash\nDEFAULT_WEBSITES=(\n    \"https://example.com\"\n    \"https://api.example.com\"\n)\n\nDEFAULT_VM_HOSTS=(\n    \"server1.example.com\"\n    \"192.168.1.100\"\n)\n```\n\n## Usage\n\n### CLI Reference\n\n```\nmonitor.sh v2.0.0 - Prometheus website \u0026 VM host monitor\n\nUsage:\n  monitor.sh [options]\n\nOptions:\n  -c, --config \u003cfile\u003e   Path to YAML config file\n      --cli             CLI-only mode (skip Prometheus file output)\n  -h, --help            Show this help\n\nExamples:\n  ./monitor.sh                              # Use hardcoded defaults\n  ./monitor.sh --config config.yaml         # Load targets from config\n  ./monitor.sh --cli                        # Quick CLI health check\n  ./monitor.sh --config config.yaml --cli   # Config + CLI-only\n```\n\n### Manual Execution\n```bash\n./monitor.sh                              # Hardcoded defaults → Prometheus output\n./monitor.sh --config config.yaml         # YAML config → Prometheus output\n./monitor.sh --cli                        # Hardcoded defaults → CLI only\n./monitor.sh --config config.yaml --cli   # YAML config → CLI only\n```\n\n### Scheduled Execution with Cron\nAdd to crontab for automated monitoring (runs every 5 minutes):\n```bash\ncrontab -e\n```\n\nAdd the following line:\n```bash\n*/5 * * * * /path/to/monitor.sh --config /path/to/config.yaml \u003e/dev/null 2\u003e\u00261\n```\n\nOr for more frequent monitoring (every minute):\n```bash\n* * * * * /path/to/monitor.sh --config /path/to/config.yaml \u003e/dev/null 2\u003e\u00261\n```\n\n## CLI-Only Mode\n\nUse `--cli` to run the script as a **standalone health checker** without any Prometheus setup:\n\n```bash\n./monitor.sh --cli\n./monitor.sh --config config.yaml --cli\n```\n\nIn this mode the script:\n- Runs all website and VM host checks in parallel\n- Displays UP/DOWN results on the terminal\n- **Skips** writing the `.prom` metrics file\n- **Skips** the textfile collector directory check\n\nThis makes it usable by anyone - no Prometheus or Node Exporter required.\n\n## Parallel Execution\n\nAll website and VM host checks run **in parallel by default**. The number of concurrent jobs is controlled by:\n\n| Source           | Setting                | Default |\n|------------------|------------------------|---------|\n| Config file      | `parallel.max_jobs`    | `5`     |\n| Script default   | `MAX_PARALLEL_JOBS`    | `5`     |\n\nEach check runs in a background subshell with isolated output files. Console results are replayed in order after all jobs complete, so the output remains deterministic.\n\n## Integration with Prometheus\n\n### Node Exporter Configuration\n\n1. **Install Node Exporter** (if not already installed)\n2. **Configure Node Exporter** to use the textfile collector:\n   Edit `/etc/systemd/system/node_exporter.service` or your Node Exporter configuration:\n\n```ini\n   [Service]\n   ExecStart=/usr/local/bin/node_exporter \\\n       --collector.textfile.directory=/opt/node_exporter/textfile_collector \\\n       --collector.textfile\n```\n\n3. **Verify metrics are being collected**:\n\n```bash\n   curl http://localhost:9100/metrics | grep website_\n   curl http://localhost:9100/metrics | grep vm_host_\n```\n  \n## Examples Output\n  ![screenshot101.png](screenshot101.png)\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheoneoh1%2Fblackbox-lite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheoneoh1%2Fblackbox-lite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheoneoh1%2Fblackbox-lite/lists"}