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