Package: nagios-api
nagios-api==========NAME----nagios-api - presents a REST-like JSON interface to NagiosSYNOPSIS--------nagios-api [OPTIONS]DEPENDENCIES------------Dependencies include: diesel, greenlet and python-openssl bindings. Theseshould be available via pip/easy_install.DESCRIPTION-----------This program provides a simple REST-like interface to Nagios. Run thison your Nagios host and then sit back and enjoy a much easier, morestraightforward way to accomplish things with Nagios. You can use thebundled nagios-cli, but you may find it easier to write your own systemfor interfacing with the API.USAGE-----Usage is pretty easy:nagios-api -p 8080 -c /var/lib/nagios3/rw/nagios.cmd \-s /var/cache/nagios3/status.dat -l /var/log/nagios3/nagios.logYou must at least provide the status file options. If you don't providethe other options, then we will disable that functionality and error toclients who request it.HTTP USAGE----------The server speaks JSON. You can either GET data from it or POST data toit and take an action. It's pretty straightforward, here's an idea ofwhat you can do from the command line:curl http://localhost:6315/stateThat calls the `state` method and returns the JSON result.curl -d '{"host": "web01", "duration": 600}' \http://localhost:6315/schedule_downtimeThis POSTs the given JSON object to the `schedule_downtime` method. Youwill note that all objects returned follow a predictable format:{"content": <object>, "result": <bool>}The `result` field is always `true` or `false`, allowing you todetermine at a glance if the command succeeded. The `content` field maybe any valid JavaScript object: an int, string, null, bool, hash, list,etc etc. What is returned depends on the method being called.NAGIOS-CLI USAGE----------------Once your API server is up and running you can access it through theincluded nagios-cli script. The script now has some decent built-in helpso you should be able to get all you need:nagios-cli -hThe original raw JSON mode is still supported by passing the --rawoption.OPTIONS--------p, --port=PORTListen on port 'PORT' for HTTP requests.-b, --bind=ADDRBind to ADDR for HTTP requests (defaults to all interfaces).-c, --command-file=FILEUse 'FILE' to write commands to Nagios. This is where externalcommands are sent. If your Nagios installation does not allowexternal commands, do not set this option.-s, --status-file=FILESet 'FILE' to the status file where Nagios stores its statusinformation. This is where we learn about the state of the world andis the only required parameter.-l, --log-file=FILEPoint 'FILE' to the location of Nagios's log file if you want toallow people to subscribe to it.-o, --allow-origin=ORIGINModern web browsers implement the Cross-Origin Resource Sharingspecification from W3C. This spec allows you to host yourJavaScript/HTML on one host and have it access an endpoint on adifferent service. This requires setting a header on the endpoint,which this option allows you to do.You can simply set this header to `*` and not worry about itif you want to allow all access. For more information see the[CORS specification](http://www.w3.org/TR/cors/).-q, --quietIf present, we will only print warning/critical messages. Useful ifyou are running this in the background.API---This program currently supports only a subset of the Nagios API. Moreis being added as it is needed. If you need something that isn't here,please consider submitting a patch!This section is organized into methods and sorted alphabetically. Eachmethod is specified as a URL and may include an integer component on thepath. Most data is passed as JSON objects in the body of a POST.acknowledge_problem~~~~~~~~~~~~~~~~~~~This method allows you to acknowledge a given problem on a host or service.*host*='STRING' [required]::Which host to act on.*service*='STRING'::Optional. If specified, act on this service.*comment*='STRING' [required]::This is required and should contain some sort of message that explains whythis alert is being acknowledged.*sticky*='BOOL'::Optional, default TRUE. When true, this acknowledgement stays until thehost enters an OK state. If false, the acknowledgement clears on ANY statechange.*notify*='BOOL'::Optional, default TRUE. Whether or not to send a notification that thisproblem has been acknowledged.*persistent*='BOOL'::Optional, default FALSE. If this is enabled, the comment given will stayon the host or service. By default, when an acknowledgement expires, thecomment associated with it is deleted.*author*='STRING'::Optional. The name of the author. This is useful in UIs if you wantto disambiguate who is doing what.add_comment~~~~~~~~~~~For a given host and/or service, add a comment. This is free-form text that caninclude whatever you want and is visible in the Nagios UI and API output.*host*='STRING' [required]::Which host to act on.*service*='STRING'::Optional. If specified, act on this service.*comment*='STRING' [required]::This is required and should contain the text of the comment you want toadd to this host or service.*persistent*='BOOL'::Optional, default FALSE. If this is enabled, the comment given will stayon the host or service until deleted manually. By default, they only stayuntil Nagios is restarted.*author*='STRING'::Optional. The name of the author. This is useful in UIs if you wantto disambiguate who is doing what.cancel_downtime~~~~~~~~~~~~~~~Very simply, this immediately lifts a downtime that is currently ineffect on a host or service. If you know the `downtime_id`, you canspecify that as a URL argument like this:curl -d "{}" http://localhost:6315/cancel_downtime/15That would cancel the downtime with `downtime_id` of 15. Most of thetime you will probably not have this information and so we allow you tocancel by host/service as well.*host*='STRING' [required]::Which host to cancel downtime from.  This must be specified if youare not using the `downtime_id` directly.*service*='STRING'::Optional. If specified, cancel any downtimes on this service.*services_too*='BOOL'::Optional. If true and you have not specified a `service` inspecific, then we will cancel all downtimes on this host and all ofthe services it has.disable_notifications~~~~~~~~~~~~~~~~~~~~~This disables alert notifications on a host or service. (As an operationalnote, you might want to schedule downtime instead. Disabling notificationshas a habit of leaving things off and people forgetting about it.)*host*='STRING' [required]::Which host to act on.*service*='STRING'::Optional. If specified, act on this service.delete_comment~~~~~~~~~~~~~~Deletes comments from a host or service. Can be used to delete all comments orjust a particular comment.*host*='STRING' [required]::Which host to act on.*service*='STRING'::Optional. If specified, act on this service.*comment_id*='INTEGER' [required]::The ID of the comment you wish to delete. You may set this to -1 to deleteall comments on the given host or service.enable_notifications~~~~~~~~~~~~~~~~~~~~This enables alert notifications on a host or service.*host*='STRING' [required]::Which host to act on.*service*='STRING'::Optional. If specified, act on this service.log~~~Simply returns the most recent 1000 items in the Nagios event log. Theseare currently unparsed. There is a plan to parse this in the future andreturn event objects.objects~~~~~~~Returns a dict with the key being hostnames and the values being a listof services defined for that host. Use this method to get the contentsof the world -- i.e., all hosts and services.remove_acknowledgement~~~~~~~~~~~~~~~~~~~~~~This method cancels an acknowledgement on a host or service.*host*='STRING' [required]::Which host to act on.*service*='STRING'::Optional. If specified, act on this service.schedule_check~~~~~~~~~~~~~~This API lets you schedule a check for a host or service. This also allowsyou to force a check.*host*='STRING' [required]::The host to schedule a check for. Required.*service*='STRING'::Optional. If present, we'll schedule a check on this service at the giventime.*check_time*='INTEGER'::Optional, defaults to now. You can specify what time you want the checkto be run at.*forced*='BOOL'::Optional, defaults to FALSE. When true, then you force Nagios to run thecheck at the given time. By default, Nagios will only run the check if itmeets the standard eligibility criteria.*output*='STRING' [required]::The plugin output to be displayed in the UI and stored.  This is asingle line of text, normally returned by checkers.schedule_downtime~~~~~~~~~~~~~~~~~This general purpose method is used for creating fixed length downtimes.This method can be used on hosts and services. You are allowed tospecify the author and comment to go with the downtime, too. The JSONparameters are:*host*='STRING' [required]::Which host to schedule a downtime for.  This must be specified.*duration*='INTEGER' [required]::How many seconds this downtime will last for. They begin immediatelyand continue for `duration` seconds before ending.*service*='STRING'::Optional. If specified, we will schedule a downtime for this serviceon the above host. If not specified, then the downtime will bescheduled for the host itself.*services_too*='BOOL'::Optional. If true and you have not specified a `service` inspecific, then we will schedule a downtime for the host and all ofthe services on that host. Potentially many downtimes are scheduled.*author*='STRING'::Optional. The name of the author. This is useful in UIs if you wantto disambiguate who is doing what.*comment*='STRING'::Optional. As above, useful in the UI.The result of this method is a text string that indicates whether ornot the downtimes have been scheduled or if a different error occurred.We do not have the ability to get the `downtime_id` that is generated,unfortunately, as that would require waiting for Nagios to regeneratethe status file.state~~~~~This method takes no parameters. It returns a large JSON objectcontaining all of the active state from Nagios. Included are all hosts,services, downtimes, comments, and other things that may be in theglobal state object.submit_result~~~~~~~~~~~~~If you are using passive service checks or you just want to submit aresult for a check, you can use this method to submit your result toNagios.*host*='STRING' [required]::The host to submit a result for.  This is required.*service*='STRING'::Optional. If specified, we will submit a result for this service onthe above host. If not specified, then the result will be submittedfor the host itself.*status*='INTEGER' [required]::The status code to set this host/service check to. If you areupdating a host's status: 0 = OK, 1 = DOWN, 2 = UNREACHABLE. Forservice checks, 0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN.*output*='STRING' [required]::The plugin output to be displayed in the UI and stored.  This is asingle line of text, normally returned by checkers.The response indicates if we successfully wrote the command to the log.AUTHOR------Written by Mark Smith <mark@qq.is> while under the employ of BumpTechnologies, Inc.COPYING-------See the LICENSE file for licensing information.