| 1 |
The NSCA-ng Protocol, Version 1 |
| 2 |
=============================== |
| 3 |
|
| 4 |
> [Holger Weiss](mailto:[email protected]) |
| 5 |
> February 2013 |
| 6 |
|
| 7 |
This is an informal description of the NSCA-ng Protocol, Version 1, used for |
| 8 |
transmitting "monitoring commands" from NSCA-ng clients to NSCA-ng servers. |
| 9 |
|
| 10 |
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", |
| 11 |
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to |
| 12 |
be interpreted as described in [RFC 2119][1]. |
| 13 |
|
| 14 |
Connection Initiation |
| 15 |
--------------------- |
| 16 |
|
| 17 |
The NSCA-ng server listens on TCP port 5668. As soon as an NSCA-ng client |
| 18 |
connects, a TLS handshake is initiated in order to establish a secure |
| 19 |
connection. Implementations MUST support TLS v1.0 as per [RFC 2246][2]. |
| 20 |
Also, the pre-shared key cipher suite `TLS_PSK_WITH_AES_256_CBC_SHA` as |
| 21 |
defined in [RFC 4279][3] MUST be offered by clients and accepted by servers. |
| 22 |
However, implementations MAY attempt to negotiate newer versions of the TLS |
| 23 |
protocol and/or other TLS cipher suites during the TLS handshake. When the |
| 24 |
TLS connection is established successfully, the client can initiate the |
| 25 |
first NSCA-ng request. All NSCA-ng data MUST be transmitted as TLS |
| 26 |
"application data". |
| 27 |
|
| 28 |
NSCA-ng Session |
| 29 |
--------------- |
| 30 |
|
| 31 |
Let's begin with an example where the client successfully transmits the |
| 32 |
`ENABLE_NOTIFICATIONS` command to the server (`C:` and `S:` indicate lines |
| 33 |
sent by the client and server, respectively): |
| 34 |
|
| 35 |
C: MOIN 1 Zm9vYmFy |
| 36 |
S: MOIN 1 |
| 37 |
C: PUSH 34 |
| 38 |
S: OKAY |
| 39 |
C: [1358980254] ENABLE_NOTIFICATIONS |
| 40 |
S: OKAY |
| 41 |
C: QUIT |
| 42 |
S: OKAY |
| 43 |
|
| 44 |
An NSCA-ng session is a sequence of one or more request-response pairs and |
| 45 |
zero or more "monitoring command" submissions. Requests and responses are |
| 46 |
CRLF-terminated lines (though implementations SHOULD also accept |
| 47 |
LF-terminated lines). The length of such a line MUST NOT exceed 1024 |
| 48 |
octets, including the CRLF-termination. |
| 49 |
|
| 50 |
Requests can only be issued by clients. A request consists of a |
| 51 |
case-insensitive four-character keyword followed by zero or more arguments. |
| 52 |
Keywords and arguments consist of printable US-ASCII characters, and are |
| 53 |
each separated by a single space character. |
| 54 |
|
| 55 |
Responses are emitted by servers and consist of a four-character keyword, |
| 56 |
which MUST be sent in all uppercase letters. |
| 57 |
|
| 58 |
The first request issued by the client (after establishing the TLS session) |
| 59 |
MUST be a `MOIN`, `PING`, or `BAIL` request. If the first request is a |
| 60 |
`MOIN` request, the last request issued by the client MUST be a `QUIT` or |
| 61 |
`BAIL` request. |
| 62 |
|
| 63 |
The remaining part of this document describes the possible client requests |
| 64 |
and server responses. "Monitoring command" submissions are described in the |
| 65 |
context of the `PUSH` request. |
| 66 |
|
| 67 |
MOIN Request |
| 68 |
------------ |
| 69 |
|
| 70 |
Synopsis: MOIN <version> <session-id> |
| 71 |
Example: MOIN 1 Zm9vYmFy |
| 72 |
|
| 73 |
The client issues a `MOIN` request in order to negotiate the protocol |
| 74 |
`<version>` and to specify a `<session-id>`. |
| 75 |
|
| 76 |
The protocol `<version>` is a positive decimal number, currently always `1`. |
| 77 |
|
| 78 |
The `<session-id>` is an arbitrary string consisting of 2--64 printable |
| 79 |
US-ASCII characters. Clients SHOULD strive for uniqueness when generating |
| 80 |
the `<session-id>`, though it's currently not referenced anywhere else in |
| 81 |
the NSCA-ng protocol. Implementations might mention the `<session-id>` when |
| 82 |
logging connection data. |
| 83 |
|
| 84 |
If a `MOIN` request is sent, it MUST be the first request of an NSCA-ng |
| 85 |
session; except that the `MOIN` request MAY be retried with different |
| 86 |
parameters after the server replied to a `MOIN` request with a `FAIL` |
| 87 |
response. |
| 88 |
|
| 89 |
On success, the server replies with a `MOIN` response. |
| 90 |
|
| 91 |
See also: <http://en.wikipedia.org/wiki/Moin> |
| 92 |
|
| 93 |
PING Request |
| 94 |
------------ |
| 95 |
|
| 96 |
Synopsis: PING <version> |
| 97 |
Example: PING 1 |
| 98 |
|
| 99 |
The protocol `<version>` is a positive decimal number, currently always `1`. |
| 100 |
|
| 101 |
If a `PING` request is sent, it MUST be the first request of an NSCA-ng |
| 102 |
session; except that the `PING` request MAY be retried with different |
| 103 |
parameters after the server replied to a `PING` request with a `FAIL` |
| 104 |
response. |
| 105 |
|
| 106 |
On success, the server replies with a `PONG` response. The TLS connection |
| 107 |
is then shut down (cleanly) by both sides. |
| 108 |
|
| 109 |
PUSH Request |
| 110 |
------------ |
| 111 |
|
| 112 |
Synopsis: PUSH <size> |
| 113 |
Example: PUSH 42 |
| 114 |
|
| 115 |
The client issues a `PUSH` request in order to initiate a "monitoring |
| 116 |
command" submission. The "monitoring command" is expected to be in the |
| 117 |
format described in the Nagios documentation. The trailing newline |
| 118 |
character MUST be included, and the submitted "monitoring command" MUST NOT |
| 119 |
be CRLF-terminated. Newline characters within the "monitoring command" |
| 120 |
(except for the trailing newline) MUST be replaced with the literal string |
| 121 |
`\n`, and backslash characters MUST be escaped with another backslash. |
| 122 |
|
| 123 |
The `<size>` parameter specifies the size of the "monitoring command" in |
| 124 |
octets, including the trailing newline character. |
| 125 |
|
| 126 |
On success, the server replies with an `OKAY` response. The client then |
| 127 |
transmits the "monitoring command". On success, the server replies with |
| 128 |
another `OKAY` response. |
| 129 |
|
| 130 |
The client MUST NOT submit multiple "monitoring commands" via a single |
| 131 |
`PUSH` request. The client MAY issue multiple `PUSH` requests per NSCA-ng |
| 132 |
session, though. |
| 133 |
|
| 134 |
NOOP Request |
| 135 |
------------ |
| 136 |
|
| 137 |
Synopsis: NOOP |
| 138 |
Example: NOOP |
| 139 |
|
| 140 |
A `NOOP` request has no effect, with the exception that any connection |
| 141 |
timeout timers on the server SHOULD be reset. |
| 142 |
|
| 143 |
On success, the server replies with an `OKAY` response. |
| 144 |
|
| 145 |
QUIT Request |
| 146 |
------------ |
| 147 |
|
| 148 |
Synopsis: QUIT |
| 149 |
Example: QUIT |
| 150 |
|
| 151 |
The client issues a `QUIT` request in order to close the NSCA-ng session. |
| 152 |
|
| 153 |
On success, the server replies with an `OKAY` response. The TLS connection |
| 154 |
is then shut down (cleanly) by both sides. |
| 155 |
|
| 156 |
BAIL Request |
| 157 |
------------ |
| 158 |
|
| 159 |
Synopsis: BAIL <message> ... |
| 160 |
Example: BAIL I'm feeling bad |
| 161 |
|
| 162 |
The client may transmit a `BAIL` request for any reason at any time. An |
| 163 |
arbitrary, human-readable `<message>` MUST be specified. |
| 164 |
|
| 165 |
The TLS connection is then shut down immediately and unconditionally (but |
| 166 |
cleanly) by both sides. |
| 167 |
|
| 168 |
MOIN Response |
| 169 |
------------- |
| 170 |
|
| 171 |
Synopsis: MOIN <version> |
| 172 |
Example: MOIN 1 |
| 173 |
|
| 174 |
The server accepts a `MOIN` request by sending a `MOIN` response. If the |
| 175 |
server doesn't support the protocol `<version>` suggested in the client's |
| 176 |
`MOIN` request, the server MUST either specify a supported protocol |
| 177 |
`<version>` in the `MOIN` response or generate a `BAIL` response. In the |
| 178 |
former case, the client MUST either accept the protocol `<version>` |
| 179 |
suggested in the server's `MOIN` response or generate a `BAIL` request. |
| 180 |
|
| 181 |
The protocol `<version>` is a positive decimal number, currently always `1`. |
| 182 |
|
| 183 |
PONG Response |
| 184 |
------------- |
| 185 |
|
| 186 |
Synopsis: PONG <version> |
| 187 |
Example: PONG 1 |
| 188 |
|
| 189 |
The server replies to a `PING` request with a `PONG` response. |
| 190 |
|
| 191 |
The protocol `<version>` is a positive decimal number, currently always `1`. |
| 192 |
|
| 193 |
The TLS connection is then shut down (cleanly) by both sides. |
| 194 |
|
| 195 |
OKAY Response |
| 196 |
------------- |
| 197 |
|
| 198 |
Synopsis: OKAY |
| 199 |
Example: OKAY |
| 200 |
|
| 201 |
The server acknowledges the current client request or "monitoring command" |
| 202 |
submission by sending an `OKAY` response. |
| 203 |
|
| 204 |
FAIL Response |
| 205 |
------------- |
| 206 |
|
| 207 |
Synopsis: FAIL <message> ... |
| 208 |
Example: FAIL You're not authorized to submit this command |
| 209 |
|
| 210 |
The server sends a `FAIL` response to reject the current client request or |
| 211 |
"monitoring command" submission. An arbitrary, human-readable `<message>` |
| 212 |
MUST be specified. |
| 213 |
|
| 214 |
The client then sends a new request. |
| 215 |
|
| 216 |
BAIL Response |
| 217 |
------------- |
| 218 |
|
| 219 |
Synopsis: BAIL <message> ... |
| 220 |
Example: BAIL I'm feeling horrible |
| 221 |
|
| 222 |
The server may transmit a `BAIL` response for any reason at any time. An |
| 223 |
arbitrary, human-readable `<message>` MUST be specified. |
| 224 |
|
| 225 |
The TLS connection is then shut down immediately and unconditionally (but |
| 226 |
cleanly) by both sides. |
| 227 |
|
| 228 |
[1]: http://tools.ietf.org/html/rfc2119 "RFC 2119" |
| 229 |
[2]: http://tools.ietf.org/html/rfc2246 "RFC 2246" |
| 230 |
[3]: http://tools.ietf.org/html/rfc4279 "RFC 4279" |
| 231 |
|
| 232 |
<!-- vim:set filetype=markdown textwidth=76 joinspaces: --> |