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
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:
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.
## <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:
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
## <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
# <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
## <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
--------------------------|---------------|-----------------
# 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
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:
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`
> 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
{ "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
projects / icinga2 / commitdiff