tyler.durden
/
icinga2
mirror of https://github.com/Icinga/icinga2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update documentation 

refs #9105
This commit is contained in:
Gunnar Beutner 2015-11-08 01:19:38 +01:00
parent d975e47c2c
commit df1d235634
4 changed files with 131 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
doc/18-language-reference.md
View File

@ -813,6 +813,22 @@ The `continue` and `break` keywords can be used to control how the loop is execu
skips over the remaining expressions for the loop body and begins the next loop evaluation. The `break` keyword
breaks out of the loop.
## <a id="constructor"></a> Constructors
In order to create a new value of a specific type constructor calls may be used.
Example:
var pd = PerfdataValue()
pd.label = "test"
pd.value = 10
You can also try to convert an existing value to another type by specifying it as an argument for the constructor call.
Example:
var s = String(3) /* Sets s to "3". */
## <a id="throw"></a> Exceptions
Built-in commands may throw exceptions to signal errors such as invalid arguments. User scripts can throw exceptions
@ -824,6 +840,12 @@ Example:
There is currently no way for scripts to catch exceptions.
## <a id="breakpoints"></a> Breakpoints
The `debugger` keyword can be used to insert a breakpoint. It may be used at any place where an assignment would also be a valid expression.
By default breakpoints have no effect unless Icinga is started with the `--script-debugger` command-line option. When the script debugger is enabled Icinga stops execution of the script when it encounters a breakpoint and spawns a console which lets the user inspect the current state of the execution environment.
## <a id="types"></a> Types
All values have a static type. The `typeof` function can be used to determine the type of a value:

76
doc/19-library-reference.md
View File

@ -17,7 +17,7 @@ bool(value) | Converts the value to a bool.
random() | Returns a random value between 0 and RAND_MAX (as defined in stdlib.h).
log(value) | Writes a message to the log. Non-string values are converted to a JSON string.
log(severity, facility, value) | Writes a message to the log. `severity` can be one of `LogDebug`, `LogNotice`, `LogInformation`, `LogWarning`, and `LogCritical`. Non-string values are converted to a JSON string.
typeof(value) | Returns the type object for a value.
typeof(value) | Returns the [Type](19-library-reference.md#type-type) object for a value.
get_time() | Returns the current UNIX timestamp.
parse_performance_data(pd) | Parses a performance data string and returns an array describing the values.
dirname(path) | Returns the directory portion of the specified path.
@ -510,6 +510,8 @@ Returns a copy of the string in reverse order.
## <a id="object-type"></a> Object type
This is the base type for all types in the Icinga application.
### <a id="object-clone"></a> Object#clone
Signature:
@ -520,9 +522,77 @@ Returns a copy of the object. Note that for object elements which are
reference values (e.g. objects such as arrays or dictionaries) the entire
object is recursively copied.
## <a id="object-to-string"></a> Object#to_string
Signature:
function to_string();
Returns a string representation for the object. Unless overridden this returns a string
of the format "Object of type '<typename>'" where <typename> is the name of the
object's type.
Example:
[ 3, true ].to_string() /* Returns "[ 3.000000, true ]" */
## <a id="object-type-field"></a> Object#type
Signature:
String type;
Returns the object's type name. This attribute is read-only.
Example:
get_host("localhost").type /* Returns "Host" */
## <a id="type-type"></a> Type type
Inherits methods from the [Object type](19-library-reference.md#object-type).
The `Type` type provides information about the underlying type of an object or scalar value.
All types are registered as global variables. For example, in order to obtain a reference to the `String` type the global variable `String` can be used.
### <a id="type-base"></a> Type#base
Signature:
Type base;
Returns a reference to the type's base type. This attribute is read-only.
Example:
Dictionary.base == Object /* Returns true, because the Dictionary type inherits directly from the Object type. */
### <a id="type-name"></a> Type#name
Signature:
String name;
Returns the name of the type.
### <a id="type-prototype"></a> Type#prototype
Signature:
Object prototype;
Returns the prototype object for the type. When an attribute is accessed on an object that doesn't exist the prototype object is checked to see if an attribute with the requested name exists there. If it does that attribute's value is returned.
The prototype functionality is used to implement methods.
Example:
3.to_string() /* Even though '3' does not have a to_string property the Number type's prototype object does. */
## <a id="array-type"></a> Array type
Inherits methods from the [object type](19-library-reference.md#object-type).
Inherits methods from the [Object type](19-library-reference.md#object-type).
### <a id="array-add"></a> Array#add
@ -616,7 +686,7 @@ Returns a new array with all elements of the current array in reverse order.
## <a id="dictionary-type"></a> Dictionary type
Inherits methods from the [object type](19-library-reference.md#object-type).
Inherits methods from the [Object type](19-library-reference.md#object-type).
### <a id="dictionary-shallow-clone"></a> Dictionary#shallow_clone

13
doc/6-object-types.md
View File

@ -1468,15 +1468,7 @@ Configuration Attributes:
# <a id="value-types"></a> Value Types
In addition to [expressions](18-language-reference.md#expressions)
used in object attribute assignments such as
* [Numeric](18-language-reference.md#numeric-literals), [duration](18-language-reference.md#duration-literals), [string](18-language-reference.md#string-literals) and [boolean](18-language-reference.md#boolean-literals) literals
* [Array](18-language-reference.md#array)
* [Dictionary](18-language-reference.md#dictionary)
Icinga 2 uses the following value types for runtime attributes
exposed via the [Icinga 2 API](9-icinga2-api.md#icinga2-api).
In addition to [configuration objects](6-object-types.md) Icinga 2 also uses a few other types to represent its internal state. The following types are exposed via the [API](9-icinga2-api.md#icinga2-api).
## <a id="value-types-checkresult"></a> CheckResult
@ -1498,8 +1490,7 @@ exposed via the [Icinga 2 API](9-icinga2-api.md#icinga2-api).
## <a id="value-types-perfdatavalue"></a> PerfdataValue
Icinga 2 parses performance data strings and exposes
the object to external interfaces (e.g. [GraphiteWriter](6-object-types.md#objecttype-graphitewriter) or the [Icinga 2 API](9-icinga2-api.md#icinga2-api)).
Icinga 2 parses performance data strings returned by check plugins and makes the information available to external interfaces (e.g. [GraphiteWriter](6-object-types.md#objecttype-graphitewriter) or the [Icinga 2 API](9-icinga2-api.md#icinga2-api)).
Name | Type | Description
--------------------------|---------------|-----------------

62
doc/9-icinga2-api.md
View File

@ -13,6 +13,12 @@ Make sure to restart Icinga 2 to enable the changes you just made:
# service icinga2 restart
If the prefer to set up the API manually you will have to perform the following steps:
* Set up X.509 certificates for Icinga 2
* Enable the `api` feature (`icinga2 feature enable api`)
* Create an `ApiUser` object for authentication
The next chapter provides a quick overview of how you can use the API.
## <a id="icinga2-api-introduction"></a> Introduction
@ -39,9 +45,9 @@ traffic remains encrypted.
By default the Icinga 2 API listens on port `5665` which is shared with
the cluster stack. The port can be changed by setting the `bind_port` attribute
in the [ApiListener](6-object-types.md#objecttype-apilistener)
configuration object in the `/etc/icinga2/features-available/api.conf`
file.
for the [ApiListener](6-object-types.md#objecttype-apilistener)
object in the `/etc/icinga2/features-available/api.conf`
configuration file.
Supported request methods:
@ -58,25 +64,6 @@ All requests apart from `GET` require that the following `Accept` header is set:
Each URL is prefixed with the API version (currently "/v1").
### <a id="icinga2-api-http-statuses"></a> HTTP Statuses
The API will return standard [HTTP statuses](https://www.ietf.org/rfc/rfc2616.txt)
including error codes.
When an error occurs, the response body will contain additional information
about the problem and its source.
A status code between 200 and 299 generally means that the request was
successful.
Return codes within the 400 range indicate that there was a problem with the
request. Either you did not authenticate correctly, you are missing the authorization
for your requested action, the requested object does not exist or the request
was malformed.
A status in the range of 500 generally means that there was a server-side problem
and Icinga 2 is unable to process your request.
### <a id="icinga2-api-responses"></a> Responses
Successful requests will send back a response body containing a `results`
@ -101,17 +88,24 @@ The output will be sent back as a JSON object:
> should gracefully handle fields it is not familiar with, for example by
> ignoring them.
### <a id="icinga2-api-requests-method-override"></a> Request Method Override
### <a id="icinga2-api-http-statuses"></a> HTTP Statuses
`GET` requests do not allow to send a request body. In case you cannot pass everything as URL parameters (e.g. complex filters or JSON-encoded dictionaries) you can use the `X-HTTP-Method-Override` header. This comes in handy when you are using HTTP proxies disallowing `PUT` or `DELETE` requests too.
The API will return standard [HTTP statuses](https://www.ietf.org/rfc/rfc2616.txt)
including error codes.
Query an existing object by sending a `POST` request with `X-HTTP-Method-Override: GET` as request header:
When an error occurs, the response body will contain additional information
about the problem and its source.
$ curl -k -s -u 'root:icinga' -H 'X-HTTP-Method-Override: GET' -X POST 'https://localhost:5665/v1/objects/hosts'
A status code between 200 and 299 generally means that the request was
successful.
Delete an existing object by sending a `POST` request with `X-HTTP-Method-Override: DELETE` as request header:
Return codes within the 400 range indicate that there was a problem with the
request. Either you did not authenticate correctly, you are missing the authorization
for your requested action, the requested object does not exist or the request
was malformed.
$ curl -k -s -u 'root:icinga' -H 'X-HTTP-Method-Override: DELETE' -X POST 'https://localhost:5665/v1/objects/hosts/icinga.org'
A status in the range of 500 generally means that there was a server-side problem
and Icinga 2 is unable to process your request.
### <a id="icinga2-api-authentication"></a> Authentication
@ -239,6 +233,18 @@ Here are the exact same query parameters as a JSON object:
{ "filter": "match(\"icinga2-node1.localdomain*\",host.name)", "attrs": [ "host.name", "host.state" ] }
### <a id="icinga2-api-requests-method-override"></a> Request Method Override
`GET` requests do not allow to send a request body. In case you cannot pass everything as URL parameters (e.g. complex filters or JSON-encoded dictionaries) you can use the `X-HTTP-Method-Override` header. This comes in handy when you are using HTTP proxies disallowing `PUT` or `DELETE` requests too.
Query an existing object by sending a `POST` request with `X-HTTP-Method-Override: GET` as request header:
$ curl -k -s -u 'root:icinga' -H 'X-HTTP-Method-Override: GET' -X POST 'https://localhost:5665/v1/objects/hosts'
Delete an existing object by sending a `POST` request with `X-HTTP-Method-Override: DELETE` as request header:
$ curl -k -s -u 'root:icinga' -H 'X-HTTP-Method-Override: DELETE' -X POST 'https://localhost:5665/v1/objects/hosts/icinga.org'
### <a id="icinga2-api-filters"></a> Filters
#### <a id="icinga2-api-simple-filters"></a> Simple Filters