{"id":14008034,"url":"https://github.com/Nordstrom/ssh_exporter","last_synced_at":"2025-07-24T03:31:37.943Z","repository":{"id":57499094,"uuid":"100543429","full_name":"Nordstrom/ssh_exporter","owner":"Nordstrom","description":"A Prometheus exporter for running SSH commands on a remote host and collecting statistics on those outputs","archived":false,"fork":false,"pushed_at":"2019-11-28T16:20:43.000Z","size":29,"stargazers_count":49,"open_issues_count":11,"forks_count":9,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-11-30T19:38:02.627Z","etag":null,"topics":["golang","golang-application","prometheus","prometheus-exporter"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Nordstrom.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}},"created_at":"2017-08-17T00:12:05.000Z","updated_at":"2024-08-22T17:10:14.000Z","dependencies_parsed_at":"2022-08-28T14:02:34.769Z","dependency_job_id":null,"html_url":"https://github.com/Nordstrom/ssh_exporter","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Nordstrom/ssh_exporter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nordstrom%2Fssh_exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nordstrom%2Fssh_exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nordstrom%2Fssh_exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nordstrom%2Fssh_exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Nordstrom","download_url":"https://codeload.github.com/Nordstrom/ssh_exporter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nordstrom%2Fssh_exporter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266789207,"owners_count":23984248,"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","status":"online","status_checked_at":"2025-07-24T02:00:09.469Z","response_time":99,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"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":["golang","golang-application","prometheus","prometheus-exporter"],"created_at":"2024-08-10T11:01:10.544Z","updated_at":"2025-07-24T03:31:37.713Z","avatar_url":"https://github.com/Nordstrom.png","language":"Go","readme":"# Prometheus ssh exporter\n\nThe ssh exporter is a [Prometheus exporter][prom-exporter] developed by [Nordstorm][nord-gh] for running ssh commands on remote hosts and collecting statistics about the output of those commands.\n\n## Use with caution\n\n*This tool was built for very specific edge case applications where you need to quickly get the results of some existing test script into Prometheus and existing exporters are not flexible enough.*\n*Before deciding to use this exporter, consider using a more specialized exporter insted.*\n\nAny time you're executing arbitrary code on a host you should be careful.\n\nDouble check that your commands are not liable to crash your systems, especially considering that **the commands will be run in parallel ssh connections**.\n\n## Usage\n\n### Pre-requisites\n\nYou'll need a go-lang environment to build the `ssh_exporter` binary as well as the following go imports:\n\n```go\nimport (\n\t\"errors\"\n\t\"flag\"\n\t\"fmt\"\n\t\"io/ioutil\"\n\t\"log\"\n\t\"net/http\"\n\t\"regexp\"\n\t\"strings\"\n\t\"sync\"\n\t\"time\"\n\n\t\"gopkg.in/yaml.v2\"\n\t\"golang.org/x/crypto/ssh\"\n\t\"github.com/prometheus/client_golang/prometheus/promhttp\"\n)\n```\n\n### Building the ssh exporter\n\nClone the repository via go ```go get github.com/Nordstrom/ssh_exporter``` or git (if cloning the repo by hand you will\nhave to update your $GOPATH) and `cd` into the directory.\nThen build the `ssh_exporter` binary with the following commands.\n\n```\n$ go build\n```\n\nIf any packages are not installed, use `go get` to download them.\n\n### Configuration Options\n\n#### \\\u003cversion\\\u003e\n\nThe version of the config file format. Currently supports one value\n```v0```\n\n#### \\\u003cscripts\\\u003e\n\nA list of scripts which might be executed by the exporter.\n\n##### \\\u003cname\\\u003e\n\nA name for the script to be executed. This is what is matched by the pattern URL variable.\nFor example with the followig config:\n\n```yaml\nversion: v0\nscripts:\n  - name: echo_output\n    script: echo \"output script\"\n    timeout: 5s\n    pattern: 'output [matches|does not match] a regex'\n    credentials:\n    - host: myhost.example.ext\n      port: 22\n      user: someuser\n      keyfile: /path/to/private/key\n    - host: second.host.example.net\n  - name: ls_var_tmp\n    script: ls /var/tmp\n    ...\n```\n\nThis request:\n```curl http://localhost:9428/probe?pattern=echo_output```\n\nWould execute\n```echo \"output script\"```\n\nAnd this request:\n```curl http://localhost:9428/probe?pattern=ls_var_tmp```\n\nWould likewise execute\n```ls /var/tmp```\n\n##### \\\u003cscript\\\u003e\n\nThe script to execute on the remote host\n\n##### \\\u003ctimeout\\\u003e\n\nHow long to wait for the command to complete.\n\n##### \\\u003cpattern\\\u003e\n\nA regex pattern to match against the command output. The normal model for scraping with Prometheus\nis to have the endpoint being scraped return statistical data which is stored rather than return a \npass/fail status. Then alerts or reports can be generated against that data. ssh_exporter is\nintended for edge case applications where you need to quickly get the results of some existing\ntest into Prometheus. It is intended to aid organizations who are migrating from some other monitoring \nsolution to Prometheus. And since Prometheus stores numeric data and not text results the ssh_exporter\ncompares \\\u003cpattern\\\u003e against the output of the command and returns a true or false.\n\n##### \\\u003ccredentials\\\u003e\n\nA list of endpoints upon which the command specified in \\\u003cscript\\\u003e will be executed.\n\n###### \\\u003chost\\\u003e\n\nThe host name or IP address upon which to run the test.\n\n###### \\\u003cport\\\u003e\n\nThe port upon which an ssh daemon is running on the remote host.\n\n###### \\\u003cuser\\\u003e\n\nThe user to connect as and run the command.\n\n###### \\\u003ckeyfile\\\u003e\n\nThe ssh private key to use for authentication.\n\nNOTE: ssh_exporter currently only supports private keys with no passphrase.\n\n#### Example\n\n**ssh_exporter config**\n```yaml\nversion: v0\nscripts:\n  - name: echo_output\n    script: echo \"This is my output!\"\n    timeout: 5s\n    pattern: '.*output!'\n    credentials:\n    - host: host1.example.com\n      port: 22\n      user: someuser\n      keyfile: /path/to/private/key\n  - name: check_var_temp_for_tars\n    script: ls /var/tmp\n    timeout: 5s\n    pattern: '.*tgz'\n    credentials:\n    - host: myhost.example.com\n      port: 22\n      user: someuser\n      keyfile: /path/to/private/key\n    - host: host2.example.com\n      port: 22\n      user: someotheruser\n      keyfile: /path/to/other/private/key\n```\n\n**Prometheus config**\n\n```\nscrape_configs:\n  - job_name: 'ssh_exporter_check_output'\n    static_configs:\n      - targets: ['localhost:9428']\n    metrics_path: /probe\n    params:\n      pattern: ['echo_output']\n\n  - job_name: 'ssh_exporter_check_var_tmp'\n    static_configs:\n      - targets: ['localhost:9428']\n    metrics_path: /probe\n    params:\n      pattern: ['check_var_temp_for_tars']\n```\n\n### Running\n\nThe config allows one to specify a list of scripts (with timeouts and match patterns) and a list of hosts to run that script on.\nScripts are run in parallel with concurrent ssh connections on all configured hosts.\n\nThe default configuration file path is `./config.yml`.\nThe `--config` flag overrides this option.\n\nThe default port `ssh_exporter` hosts its data on is `9428`; the `--port` flag overrides this option.\n\nAfter you have created a config file, start the endpoint server:\n\n```\n$ ./ssh_exporter/ssh_exporter --port=8888 --config=custom_config.yaml\n```\n\nThis will start the web server on `localhost:8888`.\n\n- `localhost:8888/`: a human readable navigation page\n- `localhost:8888/probe?pattern=\u003cregex-matcher-for-script-names\u003e`: statistics based on the scripts in the configuration file\n- `localhost:8888/metrics`: meta-statics about the app itself.\n\n### Prometheus Configuration\n\n```\nscrape_configs:\n  - job_name: 'ssh_exporter'\n    static_configs:\n      - targets: ['localhost:9428']\n    metrics_path: /probe\n    params:\n      pattern: ['.*']\n```\n\n\n## Contributing\n\nThere's a lot of work that can be done on the ssh exporter.\n\nIf you find an issue with ssh exporter don't want to make the changes yourself, search for the problem on the repos issues page.\nIf the issue or feature request is undocumented, make a new issue.\n\nIf you would like to contribute code or documentation, follow these steps:\n\n1. Clone a local copy.\n2. Make your changes on a uniquely named branch.\n3. Comment those changes.\n4. Test those changes (do as we say not as we do).\n5. Push your branch to a fork and create a Pull Request.\n\n## Testing\n\nThe tests are split into `Unit` and `Integration`.\n\n### Unit tests\n\nTo run just the `Unit` tests run the following command:\n\n```\n$ go test -run 'Unit'\n```\n\nThe unit tests require the file `test/config.yml` to exist at the base of the repository.\n\n### Integration tests\n\nThe Integration tests require a host to run scripts on\nA `Vagrantfile` has been provided for you to spin up and quickly use.\nTo use this first install [Vagrant][vagrant] and [Virtualbox][vbox] on your local host.\n\nTo run just the `Integration` tests, first spin up the host on which to run the scripts.\nIf you are using the provided Vagrant host, first run the following:\n\n```\n$ vagrant up\n```\n\nThis will take a while.\n\nIf you would like to configure a *different* host to run the integration tests on, edit `test/config.yml` to reflect the changed:\n\n- Host\n- Port\n- Username\n- Keyfile\n\n**WARNING** Make sure not to `git commit` any changes to `test/config.yml`.\n\nOnce you have configured / spun-up the testing host, run the integration tests with the following:\n\n```\n$ go test -run 'Integration'\n```\n\nTo destroy the local vagrant host run the following:\n\n```\n$ vagrant destroy   # Respond yes at the prompt\n```\n\n### All tests\n\nFor all tests, run the following:\n\n```\n$ go test\n```\n\n## Future work\n\nSome improvements that come to mind:\n\n- Safeguards ought to be implemented on the commands being run (beyond just timeout).\n- Addition of `script_files` to (more easily) run multi-command scripts.\n- Tests! Figure out a better integration test method.\n\n## Cutting a release\n\nIf you find yourself cutting a release don't panic, it's easy!\n\n0. Push a `git tag vX.Y.Z` to the repository.\n1. On your local computer get the repo setup. This will involve installing the dependencies listed at the top of the README.\n2. Run `make release`. This will create binaries for linux, darwin, and windows as well as a file with some sha256sums.\n3. Upload said binaries to a release targeting the `vX.Y.Z` tag.\n\n## Author\n\nNordstrom, Inc.\n\n## License\n\nCopyright 2017 Nordstrom, Inc.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\n[prom-exporter]: https://prometheus.io/docs/instrumenting/exporters/\n[nord-gh]: https://github.com/Nordstrom\n[vbox]: https://www.virtualbox.org/\n[vagrant]: https://vagrantup.com\n[caution]: #use-with-caution\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNordstrom%2Fssh_exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNordstrom%2Fssh_exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNordstrom%2Fssh_exporter/lists"}