Debian Codegraph @

PROTOCOL

raw
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: -->