{ "info": { "author": "Mark Smith", "author_email": "mark@qq.is", "bugtrack_url": null, "classifiers": [], "description": "nagios-api\n==========\n\n\nNAME\n----\nnagios-api - presents a REST-like JSON interface to Nagios\n\n\nSYNOPSIS\n--------\nnagios-api [OPTIONS]\n\n\nDEPENDENCIES\n------------\nDependencies include: diesel, greenlet and python-openssl bindings. These\nshould be available via pip/easy_install.\n\n\nDESCRIPTION\n-----------\nThis program provides a simple REST-like interface to Nagios. Run this\non your Nagios host and then sit back and enjoy a much easier, more\nstraightforward way to accomplish things with Nagios. You can use the\nbundled nagios-cli, but you may find it easier to write your own system\nfor interfacing with the API.\n\n\nUSAGE\n-----\nUsage is pretty easy:\n\n nagios-api -p 8080 -c /var/lib/nagios3/rw/nagios.cmd \\\n -s /var/cache/nagios3/status.dat -l /var/log/nagios3/nagios.log\n\nYou must at least provide the status file options. If you don't provide\nthe other options, then we will disable that functionality and error to\nclients who request it.\n\n\nHTTP USAGE\n----------\nThe server speaks JSON. You can either GET data from it or POST data to\nit and take an action. It's pretty straightforward, here's an idea of\nwhat you can do from the command line:\n\n curl http://localhost:6315/state\n\nThat calls the `state` method and returns the JSON result.\n\n curl -d '{\"host\": \"web01\", \"duration\": 600}' \\\n http://localhost:6315/schedule_downtime\n\nThis POSTs the given JSON object to the `schedule_downtime` method. You\nwill note that all objects returned follow a predictable format:\n\n {\"content\": , \"result\": }\n\nThe `result` field is always `true` or `false`, allowing you to\ndetermine at a glance if the command succeeded. The `content` field may\nbe any valid JavaScript object: an int, string, null, bool, hash, list,\netc etc. What is returned depends on the method being called.\n\n\nNAGIOS-CLI USAGE\n----------------\nOnce your API server is up and running you can access it through the\nincluded nagios-cli script. The script now has some decent built-in help\nso you should be able to get all you need:\n\n nagios-cli -h\n\nThe original raw JSON mode is still supported by passing the --raw\noption.\n\n\nOPTIONS\n-------\n -p, --port=PORT\n\nListen on port 'PORT' for HTTP requests.\n\n -b, --bind=ADDR\n\nBind to ADDR for HTTP requests (defaults to all interfaces).\n\n -c, --command-file=FILE\n\nUse 'FILE' to write commands to Nagios. This is where external\ncommands are sent. If your Nagios installation does not allow\nexternal commands, do not set this option.\n\n -s, --status-file=FILE\n\nSet 'FILE' to the status file where Nagios stores its status\ninformation. This is where we learn about the state of the world and\nis the only required parameter.\n\n -l, --log-file=FILE\n\nPoint 'FILE' to the location of Nagios's log file if you want to\nallow people to subscribe to it.\n\n -o, --allow-origin=ORIGIN\n\nModern web browsers implement the Cross-Origin Resource Sharing\nspecification from W3C. This spec allows you to host your\nJavaScript/HTML on one host and have it access an endpoint on a\ndifferent service. This requires setting a header on the endpoint,\nwhich this option allows you to do.\n\nYou can simply set this header to `*` and not worry about it\nif you want to allow all access. For more information see the\n[CORS specification](http://www.w3.org/TR/cors/).\n\n -q, --quiet\n\nIf present, we will only print warning/critical messages. Useful if\nyou are running this in the background.\n\n\nAPI\n---\nThis program currently supports only a subset of the Nagios API. More\nis being added as it is needed. If you need something that isn't here,\nplease consider submitting a patch!\n\nThis section is organized into methods and sorted alphabetically. Each\nmethod is specified as a URL and may include an integer component on the\npath. Most data is passed as JSON objects in the body of a POST.\n\nacknowledge_problem\n~~~~~~~~~~~~~~~~~~~\nThis method allows you to acknowledge a given problem on a host or service.\n\n*host*='STRING' [required]::\n Which host to act on.\n\n*service*='STRING'::\n Optional. If specified, act on this service.\n\n*comment*='STRING' [required]::\n This is required and should contain some sort of message that explains why\n this alert is being acknowledged.\n\n*sticky*='BOOL'::\n Optional, default TRUE. When true, this acknowledgement stays until the\n host enters an OK state. If false, the acknowledgement clears on ANY state\n change.\n\n*notify*='BOOL'::\n Optional, default TRUE. Whether or not to send a notification that this\n problem has been acknowledged.\n\n*persistent*='BOOL'::\n Optional, default FALSE. If this is enabled, the comment given will stay\n on the host or service. By default, when an acknowledgement expires, the\n comment associated with it is deleted.\n\n*author*='STRING'::\n Optional. The name of the author. This is useful in UIs if you want\n to disambiguate who is doing what.\n\nadd_comment\n~~~~~~~~~~~\nFor a given host and/or service, add a comment. This is free-form text that can\ninclude whatever you want and is visible in the Nagios UI and API output.\n\n*host*='STRING' [required]::\n Which host to act on.\n\n*service*='STRING'::\n Optional. If specified, act on this service.\n\n*comment*='STRING' [required]::\n This is required and should contain the text of the comment you want to\n add to this host or service.\n\n*persistent*='BOOL'::\n Optional, default FALSE. If this is enabled, the comment given will stay\n on the host or service until deleted manually. By default, they only stay\n until Nagios is restarted.\n\n*author*='STRING'::\n Optional. The name of the author. This is useful in UIs if you want\n to disambiguate who is doing what.\n\ncancel_downtime\n~~~~~~~~~~~~~~~\nVery simply, this immediately lifts a downtime that is currently in\neffect on a host or service. If you know the `downtime_id`, you can\nspecify that as a URL argument like this:\n\n curl -d \"{}\" http://localhost:6315/cancel_downtime/15\n\nThat would cancel the downtime with `downtime_id` of 15. Most of the\ntime you will probably not have this information and so we allow you to\ncancel by host/service as well.\n\n*host*='STRING' [required]::\n Which host to cancel downtime from. This must be specified if you\n are not using the `downtime_id` directly.\n\n*service*='STRING'::\n Optional. If specified, cancel any downtimes on this service.\n\n*services_too*='BOOL'::\n Optional. If true and you have not specified a `service` in\n specific, then we will cancel all downtimes on this host and all of\n the services it has.\n\ndisable_notifications\n~~~~~~~~~~~~~~~~~~~~~\nThis disables alert notifications on a host or service. (As an operational\nnote, you might want to schedule downtime instead. Disabling notifications\nhas a habit of leaving things off and people forgetting about it.)\n\n*host*='STRING' [required]::\n Which host to act on.\n\n*service*='STRING'::\n Optional. If specified, act on this service.\n\ndelete_comment\n~~~~~~~~~~~~~~\nDeletes comments from a host or service. Can be used to delete all comments or\njust a particular comment.\n\n*host*='STRING' [required]::\n Which host to act on.\n\n*service*='STRING'::\n Optional. If specified, act on this service.\n\n*comment_id*='INTEGER' [required]::\n The ID of the comment you wish to delete. You may set this to -1 to delete\n all comments on the given host or service.\n\nenable_notifications\n~~~~~~~~~~~~~~~~~~~~\nThis enables alert notifications on a host or service.\n\n*host*='STRING' [required]::\n Which host to act on.\n\n*service*='STRING'::\n Optional. If specified, act on this service.\n\nlog\n~~~\nSimply returns the most recent 1000 items in the Nagios event log. These\nare currently unparsed. There is a plan to parse this in the future and\nreturn event objects.\n\nobjects\n~~~~~~~\nReturns a dict with the key being hostnames and the values being a list\nof services defined for that host. Use this method to get the contents\nof the world -- i.e., all hosts and services.\n\nremove_acknowledgement\n~~~~~~~~~~~~~~~~~~~~~~\nThis method cancels an acknowledgement on a host or service.\n\n*host*='STRING' [required]::\n Which host to act on.\n\n*service*='STRING'::\n Optional. If specified, act on this service.\n\nschedule_check\n~~~~~~~~~~~~~~\nThis API lets you schedule a check for a host or service. This also allows\nyou to force a check.\n\n*host*='STRING' [required]::\n The host to schedule a check for. Required.\n\n*service*='STRING'::\n Optional. If present, we'll schedule a check on this service at the given\n time.\n\n*check_time*='INTEGER'::\n Optional, defaults to now. You can specify what time you want the check\n to be run at.\n\n*forced*='BOOL'::\n Optional, defaults to FALSE. When true, then you force Nagios to run the\n check at the given time. By default, Nagios will only run the check if it\n meets the standard eligibility criteria.\n\n*output*='STRING' [required]::\n The plugin output to be displayed in the UI and stored. This is a\n single line of text, normally returned by checkers.\n\n\nschedule_downtime\n~~~~~~~~~~~~~~~~~\nThis general purpose method is used for creating fixed length downtimes.\nThis method can be used on hosts and services. You are allowed to\nspecify the author and comment to go with the downtime, too. The JSON\nparameters are:\n\n*host*='STRING' [required]::\n Which host to schedule a downtime for. This must be specified.\n\n*duration*='INTEGER' [required]::\n How many seconds this downtime will last for. They begin immediately\n and continue for `duration` seconds before ending.\n\n*service*='STRING'::\n Optional. If specified, we will schedule a downtime for this service\n on the above host. If not specified, then the downtime will be\n scheduled for the host itself.\n\n*services_too*='BOOL'::\n Optional. If true and you have not specified a `service` in\n specific, then we will schedule a downtime for the host and all of\n the services on that host. Potentially many downtimes are scheduled.\n\n*author*='STRING'::\n Optional. The name of the author. This is useful in UIs if you want\n to disambiguate who is doing what.\n\n*comment*='STRING'::\n Optional. As above, useful in the UI.\n\nThe result of this method is a text string that indicates whether or\nnot the downtimes have been scheduled or if a different error occurred.\nWe do not have the ability to get the `downtime_id` that is generated,\nunfortunately, as that would require waiting for Nagios to regenerate\nthe status file.\n\nstate\n~~~~~\nThis method takes no parameters. It returns a large JSON object\ncontaining all of the active state from Nagios. Included are all hosts,\nservices, downtimes, comments, and other things that may be in the\nglobal state object.\n\nsubmit_result\n~~~~~~~~~~~~~\nIf you are using passive service checks or you just want to submit a\nresult for a check, you can use this method to submit your result to\nNagios.\n\n*host*='STRING' [required]::\n The host to submit a result for. This is required.\n\n*service*='STRING'::\n Optional. If specified, we will submit a result for this service on\n the above host. If not specified, then the result will be submitted\n for the host itself.\n\n*status*='INTEGER' [required]::\n The status code to set this host/service check to. If you are\n updating a host's status: 0 = OK, 1 = DOWN, 2 = UNREACHABLE. For\n service checks, 0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN.\n\n*output*='STRING' [required]::\n The plugin output to be displayed in the UI and stored. This is a\n single line of text, normally returned by checkers.\n\nThe response indicates if we successfully wrote the command to the log.\n\n\nAUTHOR\n------\nWritten by Mark Smith while under the employ of Bump\nTechnologies, Inc.\n\n\nCOPYING\n-------\nSee the LICENSE file for licensing information.", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/xb95/nagios-api", "keywords": null, "license": "BSD New (3-clause) License", "maintainer": null, "maintainer_email": null, "name": "nagios-api", "package_url": "https://pypi.org/project/nagios-api/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/nagios-api/", "project_urls": { "Download": "UNKNOWN", "Homepage": "https://github.com/xb95/nagios-api" }, "release_url": "https://pypi.org/project/nagios-api/1.2.2/", "requires_dist": null, "requires_python": null, "summary": "Control nagios using an API", "version": "1.2.2" }, "last_serial": 795168, "releases": { "1.0": [], "1.1": [ { "comment_text": "", "digests": { "md5": "00b582a4a9f6be7547e9b9ee15dd1ce6", "sha256": "9e7b4f8aadeef3b3d2958fc5186c1788719be731c53b32c03ed274c23f0587e8" }, "downloads": -1, "filename": "nagios-api-1.1.tar.gz", "has_sig": false, "md5_digest": "00b582a4a9f6be7547e9b9ee15dd1ce6", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 19024, "upload_time": "2013-02-14T23:38:42", "url": "https://files.pythonhosted.org/packages/74/79/4050306ecdcfd293a182674624826b543a2b43f446a132c6db706b9aa02f/nagios-api-1.1.tar.gz" } ], "1.2": [ { "comment_text": "built for Linux-2.6.32-35-generic-x86_64-with-glibc2.4", "digests": { "md5": "3147cfdfdf5369d4e68f3937e48fcf7e", "sha256": "d2950f79cd44ce1ce824c9aa49293ab49427008e5da468df09abc67cc7247e31" }, "downloads": -1, "filename": "nagios-api-1.2.linux-x86_64.tar.gz", "has_sig": false, "md5_digest": "3147cfdfdf5369d4e68f3937e48fcf7e", "packagetype": "bdist_dumb", "python_version": "any", "requires_python": null, "size": 21408, "upload_time": "2013-03-21T20:51:51", "url": "https://files.pythonhosted.org/packages/55/27/381ca8f01b2bdbaa44ba4d90ce76b999d4d953d2ca6a62e78ea74a8df3a6/nagios-api-1.2.linux-x86_64.tar.gz" }, { "comment_text": "", "digests": { "md5": "5ce1542e9c16b39d01a0f29dccc3cbc3", "sha256": "21304b3557518bc9e2585511288d02eb85df69bf2ecddb5d36e469c59a83bc62" }, "downloads": -1, "filename": "nagios-api-1.2.tar.gz", "has_sig": false, "md5_digest": "5ce1542e9c16b39d01a0f29dccc3cbc3", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 19472, "upload_time": "2013-03-21T20:51:48", "url": "https://files.pythonhosted.org/packages/f3/56/3378aebc3012956d933af9fa2ddccb45b81973537154df997f5d9693220a/nagios-api-1.2.tar.gz" } ], "1.2.1": [ { "comment_text": "built for Linux-2.6.32-35-generic-x86_64-with-glibc2.4", "digests": { "md5": "777ccb93e9dbe3a7bfe4783fe7f20473", "sha256": "2e52a7a47301da0e1178c6fc57c9a861668ffc955b2545aeed7b8c43fe62bdf9" }, "downloads": -1, "filename": "nagios-api-1.2.1.linux-x86_64.tar.gz", "has_sig": false, "md5_digest": "777ccb93e9dbe3a7bfe4783fe7f20473", "packagetype": "bdist_dumb", "python_version": "any", "requires_python": null, "size": 21409, "upload_time": "2013-03-21T22:08:29", "url": "https://files.pythonhosted.org/packages/d2/e2/858176f22dd2e9e192cd064e41e4cc3cc6abd65f59404cf29b7ec9334972/nagios-api-1.2.1.linux-x86_64.tar.gz" }, { "comment_text": "", "digests": { "md5": "54d23f08ebb3b6a18c133a85940afbe9", "sha256": "e5b16e29518b02e5a7faeab5f012f7971470b277114bfc35ee85d0b5fc55fcf4" }, "downloads": -1, "filename": "nagios-api-1.2.1.tar.gz", "has_sig": false, "md5_digest": "54d23f08ebb3b6a18c133a85940afbe9", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 19456, "upload_time": "2013-03-21T22:08:26", "url": "https://files.pythonhosted.org/packages/72/85/f2009719316aafd92f1890f3df99a75beb219f985b84f5116ae36ce3dc7a/nagios-api-1.2.1.tar.gz" } ], "1.2.2": [ { "comment_text": "", "digests": { "md5": "90159e2cc2550f860d7c4ab7e9bc2c94", "sha256": "b0cc1427e41fe594cccf599d3abd44ff4824cd898c5395043256c4b380fed317" }, "downloads": -1, "filename": "nagios-api-1.2.2.tar.gz", "has_sig": false, "md5_digest": "90159e2cc2550f860d7c4ab7e9bc2c94", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 20500, "upload_time": "2013-06-18T02:27:31", "url": "https://files.pythonhosted.org/packages/9d/54/a535f27a925dcbbb90819f0b4aaa535a2e29052defb6b71375eb893f335e/nagios-api-1.2.2.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "90159e2cc2550f860d7c4ab7e9bc2c94", "sha256": "b0cc1427e41fe594cccf599d3abd44ff4824cd898c5395043256c4b380fed317" }, "downloads": -1, "filename": "nagios-api-1.2.2.tar.gz", "has_sig": false, "md5_digest": "90159e2cc2550f860d7c4ab7e9bc2c94", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 20500, "upload_time": "2013-06-18T02:27:31", "url": "https://files.pythonhosted.org/packages/9d/54/a535f27a925dcbbb90819f0b4aaa535a2e29052defb6b71375eb893f335e/nagios-api-1.2.2.tar.gz" } ] }