{"id":18718645,"url":"https://github.com/agalue/onmsctl","last_synced_at":"2025-12-16T01:57:07.560Z","repository":{"id":64302533,"uuid":"196084752","full_name":"agalue/onmsctl","owner":"agalue","description":"A CLI tool for OpenNMS","archived":false,"fork":false,"pushed_at":"2024-10-14T13:22:42.000Z","size":223,"stargazers_count":11,"open_issues_count":6,"forks_count":4,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-19T18:12:02.225Z","etag":null,"topics":["cli","golang","opennms"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agalue.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,"zenodo":null}},"created_at":"2019-07-09T21:13:44.000Z","updated_at":"2024-10-14T13:22:41.000Z","dependencies_parsed_at":"2025-04-12T14:16:47.028Z","dependency_job_id":null,"html_url":"https://github.com/agalue/onmsctl","commit_stats":null,"previous_names":["opennms/onmsctl"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/agalue/onmsctl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agalue%2Fonmsctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agalue%2Fonmsctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agalue%2Fonmsctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agalue%2Fonmsctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agalue","download_url":"https://codeload.github.com/agalue/onmsctl/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agalue%2Fonmsctl/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262473799,"owners_count":23316890,"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":["cli","golang","opennms"],"created_at":"2024-11-07T13:22:23.693Z","updated_at":"2025-12-16T01:57:07.504Z","avatar_url":"https://github.com/agalue.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# onmsctl [![Go Report Card](https://goreportcard.com/badge/github.com/OpenNMS/onmsctl)](https://goreportcard.com/report/github.com/OpenNMS/onmsctl)\n\nA CLI tool for OpenNMS.\n\nThe following features have been implemented:\n\n* Manage multiple OpenNMS servers\n* Verify installed OpenNMS Version\n* Manage provisioning requisitions (replacing `provision.pl`)\n* Manage SNMP configuration (replacing `provision.pl`)\n* Manage Foreign Source definitions\n* Send events to OpenNMS (replacing `send-event.pl`)\n* Reload configuration of OpenNMS daemons\n* Enumerate collected resources and metrics (replacing `resourcecli`)\n* Manually manage the inventory (bypassing the provisioning system), useful when it is not possible to use Provisioning or Auto-Discover.\n* Support for searching entities using [FIQL](https://fiql-parser.readthedocs.io/en/stable/usage.html) (work in progress)\n\nThe reason for implementing a CLI in `Go` is that the generated binaries are self-contained, and for the first time, Windows users will be able to control OpenNMS from the command line. For example, `provision.pl` or `send-events.pl` rely on having Perl installed with some additional dependencies, which can be complicated in the environment where this is either hard or impossible to have.\n\n## Compilation\n\nMake sure to have [GoLang](https://golang.org/dl/) installed on your system. Recommended version: 1.16 or newer.\n\nTo compile the source code for your desired operating system:\n\nFor Linux:\n\n```bash\nGOOS=linux GOARCH=amd64 go build -o onmsctl onmsctl.go\n```\n\nFor Mac:\n\n```bash\nGOOS=darwin GOARCH=amd64 go build -o onmsctl onmsctl.go\n```\n\nFor Windows:\n\n```bash\nGOOS=windows GOARCH=amd64 go build -o onmsctl.exe onmsctl.go\n```\n\nThere is no need to specify parameters for your own operating system, as `go build` will be sufficient. You can also build targets for any operating system from any operating system, and the generated binary will work on itself; there is no need to install anything on the target device besides copying the generated binary file.\n\nAlternatively, in case you don't want to install `Go` on your system, but you have [Docker](https://www.docker.com) installed, you can use it to compile it:\n\n```bash\n➜ docker run -it --rm -e GO111MODULE=on -e GOOS=windows -e GOARCH=amd64 -v $(pwd):/app golang bash\nroot@3854e5d2d67c:/go# cd /app\nroot@3854e5d2d67c:/app# go build -o onmsctl.exe\nroot@3854e5d2d67c:/app# exit\n```\n\n## Usage\n\nThe binary contains help for all commands and subcommands by using `-h` or `--help`. Everything should be self-explanatory.\n\nThe following outlines several examples.\n\n0. Deploy OpenNMS\n\nThere are several ways to do that, and I'm going to use Kind and Helm:\n\n```bash\nkind create cluster --name onms\nhelm repo add bitnami https://charts.bitnami.com/bitnami\nhelm repo add opennms https://opennms.github.io/helm-charts\nhelm install onms-db bitnami/postgresql --version 15.5.38 \\\n  --set global.postgresql.auth.postgresPassword=P0stgr3s\nkubectl rollout status sts/onms-db-postgresql\nhelm install onms opennms/horizon \\\n  --set domain=test.local \\\n  --set dependencies.postgresql.hostname=onms-db-postgresql.default.svc \\\n  --set dependencies.postgresql.sslmode=disable\nkubectl rollout status sts/onms-core\nkubectl port-forward svc/onms-core 8980\n```\n\n\u003e That will take a few minutes to be ready.\n\nYour OpenNMS server would be reachable at `http://localhost:8980/opennms`.\n\nOnce you're done, use `ctrl+c` to stop the port forward and then remove the cluster:\n\n```bash\nkind delete cluster -n onms\n```\n\n1. Configure OpenNMS servers\n\nTo configure the tool, or to avoid specifying the URL, username, and password for your OpenNMS server with each request, you can create a file with the following content on `$HOME/.onms/config.yaml` or add the file on any location and create an environment variable called `ONMSCONFIG` with the location of the file.\n\nTo manipulate the content of the configuration file, please use the `onmsctl config` subcommand.\n\nFor instance, to add a new configuration entry and make it the default:\n\n```bash\n➜  onmsctl config set --name M2021 --url http://192.168.205.200:8980/opennms --user admin --passwd admin\n➜  onmsctl config default M2021\n➜  onmsctl config list\nDefault\tName\t\tUser\tURL\n*\tM2021\t\tadmin\thttp://192.168.205.200:8980/opennms\n\tlocal\t\tadmin\thttp://localhost:8980/opennms\n\n➜  onmsctl info\ndisplayVersion: 2021.1.1\nversion: 2021.1.1\npackageName: meridian\npackageDescription: OpenNMS Meridian\ndatetimeFormat:\n  zoneId: America/New_York\n  format: yyyy-MM-dd'T'HH:mm:ssxxx\n```\n\n\u003e Make sure to protect the file, as the credentials are on plain text.\n\n2. Verify the installed version of OpenNMS\n\n```bash\nonmsctl info\n```\n\nThe output would be something like this:\n\n```\ndisplayVersion: 26.2.2\nversion: 26.2.2\npackageName: opennms\npackageDescription: OpenNMS\ndatetimeFormat:\n  zoneId: America/New_York\n  format: yyyy-MM-dd'T'HH:mm:ssxxx\n```\n\n3. Build a requisition like you would do it with `provision.pl`:\n\n```bash\n➜ onmsctl inv req add Local\n➜ onmsctl inv node add Local srv01\n➜ onmsctl inv intf add Local srv01 10.0.0.1\n➜ onmsctl inv svc add Local srv01 10.0.0.1 ICMP\n➜ onmsctl inv cat add Local srv01 Servers\n➜ onmsctl inv asset set Local srv01 address1 home\n```\n\nTo visualize the content of the requisition:\n\n```bash\n➜ onmsctl inv node get Local srv01\nnodeLabel: srv01\nforeignID: srv01\ninterfaces:\n- ipAddress: 10.0.0.1\n  snmpPrimary: \"N\"\n  status: 1\n  services:\n  - name: ICMP\ncategories:\n- name: Servers\nassets:\n- name: address1\n  value: home\n```\n\nTo import the requisition:\n\n```bash\n➜ onmsctl inv req import Local\n```\n\n4. Build requisitions in `YAML` and apply it (similar to `kubernetes` workload with `kubectl`):\n\n```bash\n➜ cat \u003c\u003cEOF | onmsctl inv req apply -f -\nname: Routers\nnodes:\n- foreignID: router01\n  nodeLabel: Router-1\n  interfaces:\n  - ipAddress: 10.0.0.1\n  categories:\n  - name: Routers\n- foreignID: router02\n  nodeLabel: Router-2\n  interfaces:\n  - ipAddress: 10.0.0.2\n  categories:\n  - name: Routers\nEOF\n```\n\nThe above also works for individual nodes:\n\n```bash\n➜ cat \u003c\u003cEOF | onmsctl inv node apply -f=- Local\n foreignID: www.opennms.com\n interfaces:\n - ipAddress: www.opennms.com\n categories:\n - name: WebSites\nEOF\n```\n\nOr,\n\n```bash\n➜ onmsctl inv node apply Local '\nforeignID: www.opennms.com\ninterfaces:\n- ipAddress: www.opennms.com\ncategories:\n- name: WebSites'\n```\n\n\u003e Note that an FQDN was used instead of an IP Address (more on this below).\n\nTo get the actual content of the node:\n\n```bash\n➜ onmsctl inv node get Local www.opennms.com\nnodeLabel: www.opennms.com\nforeignID: www.opennms.com\ninterfaces:\n- ipAddress: 141.193.213.20\n  snmpPrimary: \"N\"\n  status: 1\ncategories:\n- name: WebSites\n```\n\nAs you can see, it is possible to specify FQDN instead of IP addresses, and they will be translated into IPs before sending the JSON payload to the ReST end-point for requisitions.\n\nAdditionally, for convenience, if the `node-label` is not specified, the `foreign-id` will be used.\n\n5. Configure SNMP credentials\n\nObtain the current credentials for a given IP address:\n\n```bash\n➜ onmsctl snmp get 12.0.0.1\n```\n\n\u003e For nodes behind Minions, you can specify the location as a command option.\n\nThe output would be:\n\n```\nversion: v2c\nport: 161\nretries: 1\ntimeout: 1800\ncommunity: public\nmaxRequestSize: 65535\nmaxRepetitions: 2\nmaxVarsPerPdu: 10\n```\n\nChange the credentials for a given IP address:\n\n```\n➜ onmsctl snmp set -v v2c -r 3 -t 2000 -c c0mpl1x 12.0.0.1\n```\n\n\u003e For nodes behind Minions, you can specify the location as a command option.\n\n## Upcoming features\n\n* Visualize tabular data with pagination (nodes, events, alarms, outages, notifications).\n\n* Configure scheduled outages.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagalue%2Fonmsctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagalue%2Fonmsctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagalue%2Fonmsctl/lists"}