PROTOCOL

   1 The NSCA-ng Protocol, Version 1
   2 ===============================
   3
   4 > [Holger Weiss](mailto:holger@weiss.in-berlin.de)
   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: -->