1<?xml version="1.0"?> 2<?rfc toc="yes"?><?rfc strict="yes"?><?rfc symrefs="yes"?><?rfc sortrefs="yes" ?><?rfc compact="yes" ?><?rfc subcompact="yes" ?><rfc category="info" docName="draft-stone-memcache-binary-01" ipr="trust200902" obsoletes="" updates="" submissionType="IETF" xml:lang="en"> 3 <front> 4 <title> Memcache Binary Protocol </title> 5 6 <author fullname="Aaron Stone" surname="Stone" role="editor"> 7 <organization>Six Apart, Ltd.</organization> 8 <address> 9 <postal> 10 <street>548 4th Street</street> 11 <city>San Francisco</city> 12 <region>CA</region> 13 <code>94107</code> 14 <country>USA</country> 15 </postal> 16 <email>[email protected]</email> 17 </address> 18 </author> 19 <author fullname="Trond Norbye" surname="Norbye" role="editor"> 20 <organization>Sun Microsystems, INC</organization> 21 <address> 22 <postal> 23 <street>Haakon VII g. 7B</street> 24 <city>Trondheim</city> 25 <code>NO-7485 Trondheim</code> 26 <country>Norway</country> 27 </postal> 28 <email>[email protected]</email> 29 </address> 30 </author> 31 <date day="28" month="August" year="2008"/> 32 <area>Applications</area> 33 <keyword>memcache memcached cache</keyword> 34 <abstract> 35 <t> 36 This memo explains the memcache binary protocol for informational 37 purposes. 38 </t> 39 <t> 40 Memcache is a high performance key-value cache. It is intentionally a 41 dumb cache, optimized for speed only. Applications using memcache do 42 not rely on it for data -- a persistent database with guaranteed 43 reliability is strongly recommended -- but applications can run much 44 faster when cached data is available in memcache. 45 </t> 46 </abstract> 47 </front> 48 49 <middle> 50 <section anchor="introduction" title="Introduction" toc="default"> 51 <t> 52 Memcache is a high performance key-value cache. It is intentionally a 53 dumb cache, optimized for speed only. Applications using memcache should 54 not rely on it for data -- a persistent database with guaranteed 55 reliability is strongly recommended -- but applications can run much 56 faster when cached data is available in memcache. 57 </t> 58 <t> 59 Memcache was originally written to make 60 <xref target="LJ">LiveJournal</xref> faster. It now powers all of 61 the fastest web sites that you love. 62 </t> 63 <section anchor="conventions" title="Conventions Used In This Document" toc="default"> 64 <t> 65 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 66 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 67 document are to be interpreted as described in 68 <xref target="KEYWORDS"/>. 69 </t> 70 </section> 71 </section> 72 73 <section anchor="packet" title="Packet Structure" toc="default"> 74 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 75 <preamble>General format of a packet:</preamble> 76 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 77 Byte/ 0 | 1 | 2 | 3 | 78 / | | | | 79 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 80 +---------------+---------------+---------------+---------------+ 81 0/ HEADER / 82 / / 83 / / 84 / / 85 +---------------+---------------+---------------+---------------+ 86 24/ COMMAND-SPECIFIC EXTRAS (as needed) / 87 +/ (note length in the extras length header field) / 88 +---------------+---------------+---------------+---------------+ 89 m/ Key (as needed) / 90 +/ (note length in key length header field) / 91 +---------------+---------------+---------------+---------------+ 92 n/ Value (as needed) / 93 +/ (note length is total body length header field, minus / 94 +/ sum of the extras and key length body fields) / 95 +---------------+---------------+---------------+---------------+ 96 Total 24 bytes 97 </artwork> 98 </figure> 99 100 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 101 <preamble>Request header:</preamble> 102 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 103 Byte/ 0 | 1 | 2 | 3 | 104 / | | | | 105 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 106 +---------------+---------------+---------------+---------------+ 107 0| Magic | Opcode | Key length | 108 +---------------+---------------+---------------+---------------+ 109 4| Extras length | Data type | Reserved | 110 +---------------+---------------+---------------+---------------+ 111 8| Total body length | 112 +---------------+---------------+---------------+---------------+ 113 12| Opaque | 114 +---------------+---------------+---------------+---------------+ 115 16| CAS | 116 | | 117 +---------------+---------------+---------------+---------------+ 118 Total 24 bytes 119 </artwork> 120 </figure> 121 122 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 123 <preamble>Response header:</preamble> 124 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 125 Byte/ 0 | 1 | 2 | 3 | 126 / | | | | 127 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 128 +---------------+---------------+---------------+---------------+ 129 0| Magic | Opcode | Key Length | 130 +---------------+---------------+---------------+---------------+ 131 4| Extras length | Data type | Status | 132 +---------------+---------------+---------------+---------------+ 133 8| Total body length | 134 +---------------+---------------+---------------+---------------+ 135 12| Opaque | 136 +---------------+---------------+---------------+---------------+ 137 16| CAS | 138 | | 139 +---------------+---------------+---------------+---------------+ 140 Total 24 bytes 141 </artwork> 142 </figure> 143 144 <t> 145 Header fields: 146 <list hangIndent="20" style="hanging"> 147 <t hangText="Magic">Magic number.</t> 148 <t hangText="Opcode">Command code.</t> 149 <t hangText="Key length">Length in bytes of the text key that follows the command extras.</t> 150 <t hangText="Status">Status of the response (non-zero on error).</t> 151 <t hangText="Extras length">Length in bytes of the command extras.</t> 152 <t hangText="Data type">Reserved for future use (Sean is using this soon).</t> 153 <t hangText="Reserved">Really reserved for future use (up for grabs).</t> 154 <t hangText="Total body length">Length in bytes of extra + key + value.</t> 155 <t hangText="Opaque">Will be copied back to you in the response.</t> 156 <t hangText="CAS">Data version check.</t> 157 </list> 158 </t> 159 </section> 160 161 <section anchor="values" title="Defined Values" toc="default"> 162 <section anchor="value-magic" title="Magic Byte" toc="default"> 163 <t> 164 <list hangIndent="8" style="hanging"> 165 <t hangText="0x80">Request packet for this protocol version</t> 166 <t hangText="0x81">Response packet for this protocol version</t> 167 </list> 168 </t> 169 170 <t> 171 Magic byte / version. For each version of the protocol, we'll use a 172 different request/response value pair. This is useful for protocol 173 analyzers to distinguish the nature of the packet from the direction 174 which it is moving. Note, it is common to run a memcached instance on 175 a host that also runs an application server. Such a host will both 176 send and receive memcache packets. 177 </t> 178 179 <t> 180 The version should hopefully correspond only to different meanings of 181 the command byte. In an ideal world, we will not change the header 182 format. As reserved bytes are given defined meaning, the protocol 183 version / magic byte values should be incremented. 184 </t> 185 186 <t> 187 Traffic analysis tools are encouraged to identify memcache packets 188 and provide detailed interpretation if the magic bytes are recognized 189 and otherwise to provide a generic breakdown of the packet. Note, that 190 the key and value positions can always be identified even if the magic 191 byte or command opcode are not recognized. 192 </t> 193 </section> 194 195 <section anchor="value-status" title="Response Status" toc="default"> 196 <t> 197 Possible values of this two-byte field: 198 <list hangIndent="8" style="hanging"> 199 <t hangText="0x0000">No error</t> 200 <t hangText="0x0001">Key not found</t> 201 <t hangText="0x0002">Key exists</t> 202 <t hangText="0x0003">Value too large</t> 203 <t hangText="0x0004">Invalid arguments</t> 204 <t hangText="0x0005">Item not stored</t> 205 <t hangText="0x0006">Incr/Decr on non-numeric value.</t> 206 <t hangText="0x0081">Unknown command</t> 207 <t hangText="0x0082">Out of memory</t> 208 </list> 209 </t> 210 </section> 211 212 <section anchor="value-opcodes" title="Command Opcodes" toc="default"> 213 <t> 214 Possible values of the one-byte field: 215 <list hangIndent="8" style="hanging"> 216 <t hangText="0x00">Get</t> 217 <t hangText="0x01">Set</t> 218 <t hangText="0x02">Add</t> 219 <t hangText="0x03">Replace</t> 220 <t hangText="0x04">Delete</t> 221 <t hangText="0x05">Increment</t> 222 <t hangText="0x06">Decrement</t> 223 <t hangText="0x07">Quit</t> 224 <t hangText="0x08">Flush</t> 225 <t hangText="0x09">GetQ</t> 226 <t hangText="0x0A">No-op</t> 227 <t hangText="0x0B">Version</t> 228 <t hangText="0x0C">GetK</t> 229 <t hangText="0x0D">GetKQ</t> 230 <t hangText="0x0E">Append</t> 231 <t hangText="0x0F">Prepend</t> 232 <t hangText="0x10">Stat</t> 233 <t hangText="0x11">SetQ</t> 234 <t hangText="0x12">AddQ</t> 235 <t hangText="0x13">ReplaceQ</t> 236 <t hangText="0x14">DeleteQ</t> 237 <t hangText="0x15">IncrementQ</t> 238 <t hangText="0x16">DecrementQ</t> 239 <t hangText="0x17">QuitQ</t> 240 <t hangText="0x18">FlushQ</t> 241 <t hangText="0x19">AppendQ</t> 242 <t hangText="0x1A">PrependQ</t> 243 </list> 244 </t> 245 <t> 246 As a convention all of the commands ending with "Q" for 247 Quiet. A quiet version of a command will omit responses 248 that are considered uninteresting. Whether a given response 249 is interesting is dependent upon the command. See the 250 descriptions of the 251 <xref target="command-get">set commands</xref> 252 and <xref target="command-set">set commands</xref> for 253 examples of commands that include quiet variants. 254 </t> 255 </section> 256 257 <section anchor="value-types" title="Data Types" toc="default"> 258 <t> 259 Possible values of the one-byte field: 260 <list hangIndent="8" style="hanging"> 261 <t hangText="0x00">Raw bytes</t> 262 </list> 263 </t> 264 </section> 265 </section> 266 267 <section title="Commands" toc="default"> 268 <section anchor="command-introduction" title="Introduction" toc="default"> 269 <t> 270 All communication is initiated by a request from the client, 271 and the server will respond to each request with zero or 272 multiple packets for each request. If the status code of a response 273 packet is non-nil, the body of the packet will contain a textual error 274 message. If the status code is nil, the command opcode will define the 275 layout of the body of the message. 276 </t> 277 <section anchor="command-introduction-example" title="Example" toc="default"> 278 <t> 279 The following figure illustrates the packet layout for 280 a packet with an error message. 281 </t> 282 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 283 <preamble>Packet layout:</preamble> 284 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 285 286 Byte/ 0 | 1 | 2 | 3 | 287 / | | | | 288 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 289 +---------------+---------------+---------------+---------------+ 290 0| 0x81 | 0x00 | 0x00 | 0x00 | 291 +---------------+---------------+---------------+---------------+ 292 4| 0x00 | 0x00 | 0x00 | 0x01 | 293 +---------------+---------------+---------------+---------------+ 294 8| 0x00 | 0x00 | 0x00 | 0x09 | 295 +---------------+---------------+---------------+---------------+ 296 12| 0x00 | 0x00 | 0x00 | 0x00 | 297 +---------------+---------------+---------------+---------------+ 298 16| 0x00 | 0x00 | 0x00 | 0x00 | 299 +---------------+---------------+---------------+---------------+ 300 20| 0x00 | 0x00 | 0x00 | 0x00 | 301 +---------------+---------------+---------------+---------------+ 302 24| 0x4e ('N') | 0x6f ('o') | 0x74 ('t') | 0x20 (' ') | 303 +---------------+---------------+---------------+---------------+ 304 28| 0x66 ('f') | 0x6f ('o') | 0x75 ('u') | 0x6e ('n') | 305 +---------------+---------------+---------------+---------------+ 306 32| 0x64 ('d') | 307 +---------------+ 308 Total 33 bytes (24 byte header, and 9 bytes value) 309 310Field (offset) (value) 311Magic (0) : 0x81 312Opcode (1) : 0x00 313Key length (2,3) : 0x0000 314Extra length (4) : 0x00 315Data type (5) : 0x00 316Status (6,7) : 0x0001 317Total body (8-11) : 0x00000009 318Opaque (12-15): 0x00000000 319CAS (16-23): 0x0000000000000000 320Extras : None 321Key : None 322Value (24-32): The textual string "Not found" 323 </artwork> 324 </figure> 325 </section> 326 </section> 327 328 <section anchor="command-get" title="Get, Get Quietly, Get Key, Get Key Quietly" toc="default"> 329 <t> 330 Request: 331 </t> 332 <t> 333 <list style="empty"> 334 <t>MUST NOT have extras.</t> 335 <t>MUST have key.</t> 336 <t>MUST NOT have value.</t> 337 </list> 338 </t> 339 340 <t> 341 Response (if found): 342 </t> 343 <t> 344 <list style="empty"> 345 <t>MUST have extras.</t> 346 <t>MAY have key.</t> 347 <t>MAY have value.</t> 348 </list> 349 </t> 350 351 <t> 352 <list style="symbols"> 353 <t>4 byte flags</t> 354 </list> 355 </t> 356 357 <t> 358 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 359 <preamble>Extra data for the get commands:</preamble> 360 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 361 Byte/ 0 | 1 | 2 | 3 | 362 / | | | | 363 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 364 +---------------+---------------+---------------+---------------+ 365 0| Flags | 366 +---------------+---------------+---------------+---------------+ 367 368 Total 4 bytes 369 </artwork> 370 </figure> 371 </t> 372 373 <t> 374 The get command gets a single key. The getq command is both mum 375 on cache miss and quiet, holding its response until a non-quiet 376 command is issued. Getk and getkq differs from get and getq by 377 adding the key into the response packet. 378 </t> 379 380 <t> 381 You're not guaranteed a response to a getq/getkq cache hit until 382 you send a non-getq/getkq command later, which uncorks the 383 server and bundles up IOs to send to the client in one go. 384 </t> 385 386 <t> 387 Clients should implement multi-get (still important for 388 reducing network roundtrips!) as n pipelined requests, the 389 first n-1 being getq/getkq, the last being a regular 390 get/getk. That way you're guaranteed to get a response, and 391 you know when the server's done. You can also do the naive 392 thing and send n pipelined get/getks, but then you could potentially 393 get back a lot of "NOT_FOUND" error code packets. 394 Alternatively, you can send 'n' getq/getkqs, followed by a 395 'noop' command. 396 </t> 397 398 <section anchor="command-get-example" title="Example" toc="default"> 399 <t> 400 To request the data associated with the key "Hello" the 401 following fields must be specified in the packet. 402 </t> 403 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 404 <preamble>get request:</preamble> 405 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 406 Byte/ 0 | 1 | 2 | 3 | 407 / | | | | 408 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 409 +---------------+---------------+---------------+---------------+ 410 0| 0x80 | 0x00 | 0x00 | 0x05 | 411 +---------------+---------------+---------------+---------------+ 412 4| 0x00 | 0x00 | 0x00 | 0x00 | 413 +---------------+---------------+---------------+---------------+ 414 8| 0x00 | 0x00 | 0x00 | 0x05 | 415 +---------------+---------------+---------------+---------------+ 416 12| 0x00 | 0x00 | 0x00 | 0x00 | 417 +---------------+---------------+---------------+---------------+ 418 16| 0x00 | 0x00 | 0x00 | 0x00 | 419 +---------------+---------------+---------------+---------------+ 420 20| 0x00 | 0x00 | 0x00 | 0x00 | 421 +---------------+---------------+---------------+---------------+ 422 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | 423 +---------------+---------------+---------------+---------------+ 424 28| 0x6f ('o') | 425 +---------------+ 426 427 Total 29 bytes (24 byte header, and 5 bytes key) 428 429Field (offset) (value) 430Magic (0) : 0x80 431Opcode (1) : 0x00 432Key length (2,3) : 0x0005 433Extra length (4) : 0x00 434Data type (5) : 0x00 435Reserved (6,7) : 0x0000 436Total body (8-11) : 0x00000005 437Opaque (12-15): 0x00000000 438CAS (16-23): 0x0000000000000000 439Extras : None 440Key (24-29): The textual string: "Hello" 441Value : None 442 </artwork> 443 </figure> 444 <t>If the item exist on the server the following packet is returned, 445 otherwise a packet with status code != 0 will be returned (see 446 <xref target="command-introduction">Introduction</xref>) 447 </t> 448 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 449 <preamble>get/getq response:</preamble> 450 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 451 452 Byte/ 0 | 1 | 2 | 3 | 453 / | | | | 454 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 455 +---------------+---------------+---------------+---------------+ 456 0| 0x81 | 0x00 | 0x00 | 0x00 | 457 +---------------+---------------+---------------+---------------+ 458 4| 0x04 | 0x00 | 0x00 | 0x00 | 459 +---------------+---------------+---------------+---------------+ 460 8| 0x00 | 0x00 | 0x00 | 0x09 | 461 +---------------+---------------+---------------+---------------+ 462 12| 0x00 | 0x00 | 0x00 | 0x00 | 463 +---------------+---------------+---------------+---------------+ 464 16| 0x00 | 0x00 | 0x00 | 0x00 | 465 +---------------+---------------+---------------+---------------+ 466 20| 0x00 | 0x00 | 0x00 | 0x01 | 467 +---------------+---------------+---------------+---------------+ 468 24| 0xde | 0xad | 0xbe | 0xef | 469 +---------------+---------------+---------------+---------------+ 470 28| 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | 0x6c ('l') | 471 +---------------+---------------+---------------+---------------+ 472 32| 0x64 ('d') | 473 +---------------+ 474 475 Total 33 bytes (24 byte header, 4 byte extras and 5 byte value) 476 477Field (offset) (value) 478Magic (0) : 0x81 479Opcode (1) : 0x00 480Key length (2,3) : 0x0000 481Extra length (4) : 0x04 482Data type (5) : 0x00 483Status (6,7) : 0x0000 484Total body (8-11) : 0x00000009 485Opaque (12-15): 0x00000000 486CAS (16-23): 0x0000000000000001 487Extras : 488 Flags (24-27): 0xdeadbeef 489Key : None 490Value (28-32): The textual string "World" 491 </artwork> 492 </figure> 493 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 494 <preamble>getk/getkq response:</preamble> 495 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 496 497 Byte/ 0 | 1 | 2 | 3 | 498 / | | | | 499 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 500 +---------------+---------------+---------------+---------------+ 501 0| 0x81 | 0x00 | 0x00 | 0x05 | 502 +---------------+---------------+---------------+---------------+ 503 4| 0x04 | 0x00 | 0x00 | 0x00 | 504 +---------------+---------------+---------------+---------------+ 505 8| 0x00 | 0x00 | 0x00 | 0x09 | 506 +---------------+---------------+---------------+---------------+ 507 12| 0x00 | 0x00 | 0x00 | 0x00 | 508 +---------------+---------------+---------------+---------------+ 509 16| 0x00 | 0x00 | 0x00 | 0x00 | 510 +---------------+---------------+---------------+---------------+ 511 20| 0x00 | 0x00 | 0x00 | 0x01 | 512 +---------------+---------------+---------------+---------------+ 513 24| 0xde | 0xad | 0xbe | 0xef | 514 +---------------+---------------+---------------+---------------+ 515 28| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | 516 +---------------+---------------+---------------+---------------+ 517 32| 0x6f ('o') | 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | 518 +---------------+---------------+---------------+---------------+ 519 36| 0x6c ('l') | 0x64 ('d') | 520 +---------------+---------------+ 521 522 Total 38 bytes (24 byte header, 4 byte extras, 5 byte key 523 and 5 byte value) 524 525Field (offset) (value) 526Magic (0) : 0x81 527Opcode (1) : 0x00 528Key length (2,3) : 0x0005 529Extra length (4) : 0x04 530Data type (5) : 0x00 531Status (6,7) : 0x0000 532Total body (8-11) : 0x0000000E 533Opaque (12-15): 0x00000000 534CAS (16-23): 0x0000000000000001 535Extras : 536 Flags (24-27): 0xdeadbeef 537Key (28-32): The textual string: "Hello" 538Value (33-37): The textual string: "World" 539 </artwork> 540 </figure> 541 </section> 542 </section> 543 544 <section anchor="command-set" title="Set, Add, Replace" toc="default"> 545 <t> 546 <list style="empty"> 547 <t>MUST have extras.</t> 548 <t>MUST have key.</t> 549 <t>MUST have value.</t> 550 </list> 551 </t> 552 553 <t> 554 <list style="symbols"> 555 <t>4 byte flags</t> 556 <t>4 byte expiration time</t> 557 </list> 558 </t> 559 560 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 561 <preamble>Extra data for set/add/replace:</preamble> 562 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 563 Byte/ 0 | 1 | 2 | 3 | 564 / | | | | 565 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 566 +---------------+---------------+---------------+---------------+ 567 0| Flags | 568 +---------------+---------------+---------------+---------------+ 569 4| Expiration | 570 +---------------+---------------+---------------+---------------+ 571 Total 8 bytes 572 </artwork> 573 </figure> 574 575 <t> 576 If the Data Version Check (CAS) is nonzero, the requested 577 operation MUST only succeed if the item exists and has a CAS value 578 identical to the provided value. 579 </t> 580 581 <t> 582 Add MUST fail if the item already exist. 583 </t> 584 585 <t> 586 Replace MUST fail if the item doesn't exist. 587 </t> 588 589 <t> 590 Set should store the data unconditionally if the item exists 591 or not. 592 </t> 593 594 <t> 595 Quiet mutations only return responses on failure. Success 596 is considered the general case and is suppressed when in 597 quiet mode, but errors should not be allowed to go 598 unnoticed. 599 </t> 600 601 <section anchor="command-set-example" title="Example" toc="default"> 602 <t>The following figure shows an add-command for 603 <list style="empty"> 604 <t>Key: "Hello"</t> 605 <t>Value: "World"</t> 606 <t>Flags: 0xdeadbeef</t> 607 <t>Expiry: in two hours</t> 608 </list> 609 </t> 610 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 611 <preamble>Add request:</preamble> 612 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 613 614 Byte/ 0 | 1 | 2 | 3 | 615 / | | | | 616 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 617 +---------------+---------------+---------------+---------------+ 618 0| 0x80 | 0x02 | 0x00 | 0x05 | 619 +---------------+---------------+---------------+---------------+ 620 4| 0x08 | 0x00 | 0x00 | 0x00 | 621 +---------------+---------------+---------------+---------------+ 622 8| 0x00 | 0x00 | 0x00 | 0x12 | 623 +---------------+---------------+---------------+---------------+ 624 12| 0x00 | 0x00 | 0x00 | 0x00 | 625 +---------------+---------------+---------------+---------------+ 626 16| 0x00 | 0x00 | 0x00 | 0x00 | 627 +---------------+---------------+---------------+---------------+ 628 20| 0x00 | 0x00 | 0x00 | 0x00 | 629 +---------------+---------------+---------------+---------------+ 630 24| 0xde | 0xad | 0xbe | 0xef | 631 +---------------+---------------+---------------+---------------+ 632 28| 0x00 | 0x00 | 0x1c | 0x20 | 633 +---------------+---------------+---------------+---------------+ 634 32| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | 635 +---------------+---------------+---------------+---------------+ 636 36| 0x6f ('o') | 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | 637 +---------------+---------------+---------------+---------------+ 638 40| 0x6c ('l') | 0x64 ('d') | 639 +---------------+---------------+ 640 641 Total 42 bytes (24 byte header, 8 byte extras, 5 byte key and 642 5 byte value) 643 644Field (offset) (value) 645Magic (0) : 0x80 646Opcode (1) : 0x02 647Key length (2,3) : 0x0005 648Extra length (4) : 0x08 649Data type (5) : 0x00 650Reserved (6,7) : 0x0000 651Total body (8-11) : 0x00000012 652Opaque (12-15): 0x00000000 653CAS (16-23): 0x0000000000000000 654Extras : 655 Flags (24-27): 0xdeadbeef 656 Expiry (28-31): 0x00001c20 657Key (32-36): The textual string "Hello" 658Value (37-41): The textual string "World" 659 </artwork> 660 </figure> 661 <t> 662 The response-packet contains no extra data, and the result of the 663 operation is signaled through the status code. If the command 664 succeeds, the CAS value for the item is returned in the CAS-field 665 of the packet. 666 </t> 667 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 668 <preamble>Successful add response:</preamble> 669 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 670 671 Byte/ 0 | 1 | 2 | 3 | 672 / | | | | 673 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 674 +---------------+---------------+---------------+---------------+ 675 0| 0x81 | 0x02 | 0x00 | 0x00 | 676 +---------------+---------------+---------------+---------------+ 677 4| 0x00 | 0x00 | 0x00 | 0x00 | 678 +---------------+---------------+---------------+---------------+ 679 8| 0x00 | 0x00 | 0x00 | 0x00 | 680 +---------------+---------------+---------------+---------------+ 681 12| 0x00 | 0x00 | 0x00 | 0x00 | 682 +---------------+---------------+---------------+---------------+ 683 16| 0x00 | 0x00 | 0x00 | 0x00 | 684 +---------------+---------------+---------------+---------------+ 685 20| 0x00 | 0x00 | 0x00 | 0x01 | 686 +---------------+---------------+---------------+---------------+ 687 688 Total 24 bytes 689 690Field (offset) (value) 691Magic (0) : 0x81 692Opcode (1) : 0x02 693Key length (2,3) : 0x0000 694Extra length (4) : 0x00 695Data type (5) : 0x00 696Status (6,7) : 0x0000 697Total body (8-11) : 0x00000000 698Opaque (12-15): 0x00000000 699CAS (16-23): 0x0000000000000001 700Extras : None 701Key : None 702Value : None 703 </artwork> 704 </figure> 705 </section> 706 </section> 707 708 <section anchor="command-delete" title="Delete" toc="default"> 709 <t> 710 <list style="empty"> 711 <t>MUST NOT have extras.</t> 712 <t>MUST have key.</t> 713 <t>MUST NOT have value.</t> 714 </list> 715 </t> 716 717 <t> 718 Delete the item with the specific key. 719 </t> 720 721 <section anchor="command-delete-example" title="Example" toc="default"> 722 <t>The following figure shows a delete message for the 723 item "Hello".</t> 724 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 725 <preamble>Delete request:</preamble> 726 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 727 Byte/ 0 | 1 | 2 | 3 | 728 / | | | | 729 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 730 +---------------+---------------+---------------+---------------+ 731 0| 0x80 | 0x04 | 0x00 | 0x05 | 732 +---------------+---------------+---------------+---------------+ 733 4| 0x00 | 0x00 | 0x00 | 0x00 | 734 +---------------+---------------+---------------+---------------+ 735 8| 0x00 | 0x00 | 0x00 | 0x05 | 736 +---------------+---------------+---------------+---------------+ 737 12| 0x00 | 0x00 | 0x00 | 0x00 | 738 +---------------+---------------+---------------+---------------+ 739 16| 0x00 | 0x00 | 0x00 | 0x00 | 740 +---------------+---------------+---------------+---------------+ 741 20| 0x00 | 0x00 | 0x00 | 0x00 | 742 +---------------+---------------+---------------+---------------+ 743 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | 744 +---------------+---------------+---------------+---------------+ 745 28| 0x6f ('o') | 746 +---------------+ 747 748 Total 29 bytes (24 byte header, 5 byte value) 749 750Field (offset) (value) 751Magic (0) : 0x80 752Opcode (1) : 0x04 753Key length (2,3) : 0x0005 754Extra length (4) : 0x00 755Data type (5) : 0x00 756Reserved (6,7) : 0x0000 757Total body (8-11) : 0x00000005 758Opaque (12-15): 0x00000000 759CAS (16-23): 0x0000000000000000 760Extras : None 761Key : The textual string "Hello" 762Value : None 763 </artwork> 764 </figure> 765 <t> 766 The response-packet contains no extra data, and the result of the 767 operation is signaled through the status code. 768 </t> 769 </section> 770 </section> 771 772 <section anchor="command-incr" title="Increment, Decrement" toc="default"> 773 <t> 774 <list style="empty"> 775 <t>MUST have extras.</t> 776 <t>MUST have key.</t> 777 <t>MUST NOT have value.</t> 778 </list> 779 </t> 780 781 <t> 782 <list style="symbols"> 783 <t>8 byte value to add / subtract</t> 784 <t>8 byte initial value (unsigned)</t> 785 <t>4 byte expiration time</t> 786 </list> 787 </t> 788 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 789 <preamble>Extra data for incr/decr:</preamble> 790 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 791 Byte/ 0 | 1 | 2 | 3 | 792 / | | | | 793 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 794 +---------------+---------------+---------------+---------------+ 795 0| Amount to add | 796 | | 797 +---------------+---------------+---------------+---------------+ 798 8| Initial value | 799 | | 800 +---------------+---------------+---------------+---------------+ 801 16| Expiration | 802 +---------------+---------------+---------------+---------------+ 803 Total 20 bytes 804 </artwork> 805 </figure> 806 807 <t> 808 These commands will either add or remove the specified 809 amount to the requested counter. 810 </t> 811 <t> 812 If the counter does not exist, one of two things may happen: 813 </t> 814 <t> 815 <list style="numbers"> 816 <t>If the expiration value is all one-bits (0xffffffff), the 817 operation will fail with NOT_FOUND.</t> 818 <t>For all other expiration values, the operation will succeed 819 by seeding the value for this key with the provided initial 820 value to expire with the provided expiration time. The flags 821 will be set to zero.</t> 822 </list> 823 </t> 824 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 825 <preamble>incr/decr response body:</preamble> 826 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 827 Byte/ 0 | 1 | 2 | 3 | 828 / | | | | 829 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 830 +---------------+---------------+---------------+---------------+ 831 0| 64-bit unsigned response. | 832 | | 833 +---------------+---------------+---------------+---------------+ 834 Total 8 bytes 835 </artwork> 836 </figure> 837 <section anchor="command-incr-example" title="Example" toc="default"> 838 <t>The following figure shows an incr-command for 839 <list style="empty"> 840 <t>Key: "counter"</t> 841 <t>Delta: 0x01</t> 842 <t>Initial: 0x00</t> 843 <t>Expiry: in two hours</t> 844 </list> 845 </t> 846 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 847 <preamble>Increment request:</preamble> 848 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 849 850 Byte/ 0 | 1 | 2 | 3 | 851 / | | | | 852 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 853 +---------------+---------------+---------------+---------------+ 854 0| 0x80 | 0x05 | 0x00 | 0x07 | 855 +---------------+---------------+---------------+---------------+ 856 4| 0x14 | 0x00 | 0x00 | 0x00 | 857 +---------------+---------------+---------------+---------------+ 858 8| 0x00 | 0x00 | 0x00 | 0x1b | 859 +---------------+---------------+---------------+---------------+ 860 12| 0x00 | 0x00 | 0x00 | 0x00 | 861 +---------------+---------------+---------------+---------------+ 862 16| 0x00 | 0x00 | 0x00 | 0x00 | 863 +---------------+---------------+---------------+---------------+ 864 20| 0x00 | 0x00 | 0x00 | 0x00 | 865 +---------------+---------------+---------------+---------------+ 866 24| 0x00 | 0x00 | 0x00 | 0x00 | 867 +---------------+---------------+---------------+---------------+ 868 28| 0x00 | 0x00 | 0x00 | 0x01 | 869 +---------------+---------------+---------------+---------------+ 870 32| 0x00 | 0x00 | 0x00 | 0x00 | 871 +---------------+---------------+---------------+---------------+ 872 36| 0x00 | 0x00 | 0x00 | 0x00 | 873 +---------------+---------------+---------------+---------------+ 874 40| 0x00 | 0x00 | 0x1c | 0x20 | 875 +---------------+---------------+---------------+---------------+ 876 44| 0x63 ('c') | 0x6f ('o') | 0x75 ('u') | 0x6e ('n') | 877 +---------------+---------------+---------------+---------------+ 878 48| 0x74 ('t') | 0x65 ('e') | 0x72 ('r') | 879 +---------------+---------------+---------------+ 880 Total 51 bytes (24 byte header, 20 byte extras, 7 byte key) 881 882Field (offset) (value) 883Magic (0) : 0x80 884Opcode (1) : 0x05 885Key length (2,3) : 0x0007 886Extra length (4) : 0x14 887Data type (5) : 0x00 888Reserved (6,7) : 0x0000 889Total body (8-11) : 0x0000001b 890Opaque (12-15): 0x00000000 891CAS (16-23): 0x0000000000000000 892Extras : 893 delta (24-31): 0x0000000000000001 894 initial (32-39): 0x0000000000000000 895 expiration (40-43): 0x00001c20 896Key : Textual string "counter" 897Value : None 898 </artwork> 899 </figure> 900 <t> 901 If the key doesn't exist, the server will respond with the 902 initial value. If not the incremented value will be returned. 903 Let's assume that the key didn't exist, so the initial value 904 is returned. 905 </t> 906 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 907 <preamble>Increment response:</preamble> 908 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 909 Byte/ 0 | 1 | 2 | 3 | 910 / | | | | 911 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 912 +---------------+---------------+---------------+---------------+ 913 0| 0x81 | 0x05 | 0x00 | 0x00 | 914 +---------------+---------------+---------------+---------------+ 915 4| 0x00 | 0x00 | 0x00 | 0x00 | 916 +---------------+---------------+---------------+---------------+ 917 8| 0x00 | 0x00 | 0x00 | 0x08 | 918 +---------------+---------------+---------------+---------------+ 919 12| 0x00 | 0x00 | 0x00 | 0x00 | 920 +---------------+---------------+---------------+---------------+ 921 16| 0x00 | 0x00 | 0x00 | 0x00 | 922 +---------------+---------------+---------------+---------------+ 923 20| 0x00 | 0x00 | 0x00 | 0x05 | 924 +---------------+---------------+---------------+---------------+ 925 24| 0x00 | 0x00 | 0x00 | 0x00 | 926 +---------------+---------------+---------------+---------------+ 927 28| 0x00 | 0x00 | 0x00 | 0x00 | 928 +---------------+---------------+---------------+---------------+ 929 Total 32 bytes (24 byte header, 8 byte value) 930 931Field (offset) (value) 932Magic (0) : 0x81 933Opcode (1) : 0x05 934Key length (2,3) : 0x0000 935Extra length (4) : 0x00 936Data type (5) : 0x00 937Status (6,7) : 0x0000 938Total body (8-11) : 0x00000008 939Opaque (12-15): 0x00000000 940CAS (16-23): 0x0000000000000005 941Extras : None 942Key : None 943Value : 0x0000000000000000 944 </artwork> 945 </figure> 946 </section> 947 </section> 948 949 <section anchor="command-quit" title="quit" toc="default"> 950 <t> 951 <list style="empty"> 952 <t>MUST NOT have extras.</t> 953 <t>MUST NOT have key.</t> 954 <t>MUST NOT have value.</t> 955 </list> 956 </t> 957 958 <t> 959 Close the connection to the server. 960 </t> 961 962 <section anchor="command-quit-example" title="Example" toc="default"> 963 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 964 <preamble>Quit request:</preamble> 965 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 966 Byte/ 0 | 1 | 2 | 3 | 967 / | | | | 968 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 969 +---------------+---------------+---------------+---------------+ 970 0| 0x80 | 0x07 | 0x00 | 0x00 | 971 +---------------+---------------+---------------+---------------+ 972 4| 0x00 | 0x00 | 0x00 | 0x00 | 973 +---------------+---------------+---------------+---------------+ 974 8| 0x00 | 0x00 | 0x00 | 0x00 | 975 +---------------+---------------+---------------+---------------+ 976 12| 0x00 | 0x00 | 0x00 | 0x00 | 977 +---------------+---------------+---------------+---------------+ 978 16| 0x00 | 0x00 | 0x00 | 0x00 | 979 +---------------+---------------+---------------+---------------+ 980 20| 0x00 | 0x00 | 0x00 | 0x00 | 981 +---------------+---------------+---------------+---------------+ 982 Total 24 bytes 983 984Field (offset) (value) 985Magic (0) : 0x80 986Opcode (1) : 0x07 987Key length (2,3) : 0x0000 988Extra length (4) : 0x00 989Data type (5) : 0x00 990Reserved (6,7) : 0x0000 991Total body (8-11) : 0x00000000 992Opaque (12-15): 0x00000000 993CAS (16-23): 0x0000000000000000 994Extras : None 995Key : None 996Value : None 997 </artwork> 998 </figure> 999 <t> 1000 The response-packet contains no extra data, and the result of the 1001 operation is signaled through the status code. The server will 1002 then close the connection. 1003 </t> 1004 </section> 1005 </section> 1006 1007 <section anchor="command-flush" title="Flush" toc="default"> 1008 <t> 1009 <list style="empty"> 1010 <t>MAY have extras.</t> 1011 <t>MUST NOT have key.</t> 1012 <t>MUST NOT have value.</t> 1013 </list> 1014 </t> 1015 1016 <t> 1017 <list style="symbols"> 1018 <t>4 byte expiration time</t> 1019 </list> 1020 </t> 1021 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 1022 <preamble>Extra data for flush:</preamble> 1023 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 1024 Byte/ 0 | 1 | 2 | 3 | 1025 / | | | | 1026 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 1027 +---------------+---------------+---------------+---------------+ 1028 0| Expiration | 1029 +---------------+---------------+---------------+---------------+ 1030 Total 4 bytes 1031 </artwork> 1032 </figure> 1033 <t> 1034 Flush the items in the cache now or some time in the future as 1035 specified by the expiration field. See the documentation of the 1036 textual protocol for the full description on how to specify the 1037 expiration time. 1038 </t> 1039 <section anchor="command-flush-example" title="Example" toc="default"> 1040 <t> 1041 To flush the cache (delete all items) in two hours, the set 1042 the following values in the request 1043 </t> 1044 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 1045 <preamble>Flush request:</preamble> 1046 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 1047 Byte/ 0 | 1 | 2 | 3 | 1048 / | | | | 1049 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 1050 +---------------+---------------+---------------+---------------+ 1051 0| 0x80 | 0x08 | 0x00 | 0x00 | 1052 +---------------+---------------+---------------+---------------+ 1053 4| 0x04 | 0x00 | 0x00 | 0x00 | 1054 +---------------+---------------+---------------+---------------+ 1055 8| 0x00 | 0x00 | 0x00 | 0x04 | 1056 +---------------+---------------+---------------+---------------+ 1057 12| 0x00 | 0x00 | 0x00 | 0x00 | 1058 +---------------+---------------+---------------+---------------+ 1059 16| 0x00 | 0x00 | 0x00 | 0x00 | 1060 +---------------+---------------+---------------+---------------+ 1061 20| 0x00 | 0x00 | 0x00 | 0x00 | 1062 +---------------+---------------+---------------+---------------+ 1063 24| 0x00 | 0x00 | 0x1c | 0x20 | 1064 +---------------+---------------+---------------+---------------+ 1065 Total 28 bytes (24 byte header, 4 byte body) 1066 1067Field (offset) (value) 1068Magic (0) : 0x80 1069Opcode (1) : 0x08 1070Key length (2,3) : 0x0000 1071Extra length (4) : 0x04 1072Data type (5) : 0x00 1073Reserved (6,7) : 0x0000 1074Total body (8-11) : 0x00000004 1075Opaque (12-15): 0x00000000 1076CAS (16-23): 0x0000000000000000 1077Extras : 1078 Expiry (24-27): 0x00001c20 1079Key : None 1080Value : None 1081 </artwork> 1082 </figure> 1083 <t> 1084 The response-packet contains no extra data, and the result of the 1085 operation is signaled through the status code. 1086 </t> 1087 </section> 1088 </section> 1089 <section anchor="command-noop" title="noop" toc="default"> 1090 <t> 1091 <list style="empty"> 1092 <t>MUST NOT have extras.</t> 1093 <t>MUST NOT have key.</t> 1094 <t>MUST NOT have value.</t> 1095 </list> 1096 </t> 1097 1098 <t> 1099 Used as a keep alive. Flushes outstanding getq/getkq's. 1100 </t> 1101 <section anchor="command-noop-example" title="Example" toc="default"> 1102 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 1103 <preamble>Noop request:</preamble> 1104 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 1105 Byte/ 0 | 1 | 2 | 3 | 1106 / | | | | 1107 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 1108 +---------------+---------------+---------------+---------------+ 1109 0| 0x80 | 0x0a | 0x00 | 0x00 | 1110 +---------------+---------------+---------------+---------------+ 1111 4| 0x00 | 0x00 | 0x00 | 0x00 | 1112 +---------------+---------------+---------------+---------------+ 1113 8| 0x00 | 0x00 | 0x00 | 0x00 | 1114 +---------------+---------------+---------------+---------------+ 1115 12| 0x00 | 0x00 | 0x00 | 0x00 | 1116 +---------------+---------------+---------------+---------------+ 1117 16| 0x00 | 0x00 | 0x00 | 0x00 | 1118 +---------------+---------------+---------------+---------------+ 1119 20| 0x00 | 0x00 | 0x00 | 0x00 | 1120 +---------------+---------------+---------------+---------------+ 1121 Total 24 bytes 1122 1123Field (offset) (value) 1124Magic (0) : 0x80 1125Opcode (1) : 0x0a 1126Key length (2,3) : 0x0000 1127Extra length (4) : 0x00 1128Data type (5) : 0x00 1129Reserved (6,7) : 0x0000 1130Total body (8-11) : 0x00000000 1131Opaque (12-15): 0x00000000 1132CAS (16-23): 0x0000000000000000 1133Extras : None 1134Key : None 1135Value : None 1136 </artwork> 1137 </figure> 1138 <t> 1139 The response-packet contains no extra data, and the result of the 1140 operation is signaled through the status code. 1141 </t> 1142 </section> 1143 </section> 1144 1145 <section anchor="command-version" title="version" toc="default"> 1146 <t> 1147 <list style="empty"> 1148 <t>MUST NOT have extras.</t> 1149 <t>MUST NOT have key.</t> 1150 <t>MUST NOT have value.</t> 1151 </list> 1152 </t> 1153 1154 <t> 1155 Request the server version. 1156 </t> 1157 <t> 1158 The server responds with a packet containing the version string 1159 in the body with the following format: "x.y.z" 1160 </t> 1161 <section anchor="command-version-example" title="Example" toc="default"> 1162 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 1163 <preamble>Version request:</preamble> 1164 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 1165 Byte/ 0 | 1 | 2 | 3 | 1166 / | | | | 1167 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 1168 +---------------+---------------+---------------+---------------+ 1169 0| 0x80 | 0x0b | 0x00 | 0x00 | 1170 +---------------+---------------+---------------+---------------+ 1171 4| 0x00 | 0x00 | 0x00 | 0x00 | 1172 +---------------+---------------+---------------+---------------+ 1173 8| 0x00 | 0x00 | 0x00 | 0x00 | 1174 +---------------+---------------+---------------+---------------+ 1175 12| 0x00 | 0x00 | 0x00 | 0x00 | 1176 +---------------+---------------+---------------+---------------+ 1177 16| 0x00 | 0x00 | 0x00 | 0x00 | 1178 +---------------+---------------+---------------+---------------+ 1179 20| 0x00 | 0x00 | 0x00 | 0x00 | 1180 +---------------+---------------+---------------+---------------+ 1181 Total 24 bytes 1182 1183Field (offset) (value) 1184Magic (0) : 0x80 1185Opcode (1) : 0x0b 1186Key length (2,3) : 0x0000 1187Extra length (4) : 0x00 1188Data type (5) : 0x00 1189Reserved (6,7) : 0x0000 1190Total body (8-11) : 0x00000000 1191Opaque (12-15): 0x00000000 1192CAS (16-23): 0x0000000000000000 1193Extras : None 1194 </artwork> 1195 </figure> 1196 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 1197 <preamble>Version response:</preamble> 1198 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 1199 Byte/ 0 | 1 | 2 | 3 | 1200 / | | | | 1201 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 1202 +---------------+---------------+---------------+---------------+ 1203 0| 0x81 | 0x0b | 0x00 | 0x00 | 1204 +---------------+---------------+---------------+---------------+ 1205 4| 0x00 | 0x00 | 0x00 | 0x00 | 1206 +---------------+---------------+---------------+---------------+ 1207 8| 0x00 | 0x00 | 0x00 | 0x05 | 1208 +---------------+---------------+---------------+---------------+ 1209 12| 0x00 | 0x00 | 0x00 | 0x00 | 1210 +---------------+---------------+---------------+---------------+ 1211 16| 0x00 | 0x00 | 0x00 | 0x00 | 1212 +---------------+---------------+---------------+---------------+ 1213 20| 0x00 | 0x00 | 0x00 | 0x00 | 1214 +---------------+---------------+---------------+---------------+ 1215 24| 0x31 ('1') | 0x2e ('.') | 0x33 ('3') | 0x2e ('.') | 1216 +---------------+---------------+---------------+---------------+ 1217 28| 0x31 ('1') | 1218 +---------------+ 1219 Total 29 bytes (24 byte header, 5 byte body) 1220 1221Field (offset) (value) 1222Magic (0) : 0x81 1223Opcode (1) : 0x0b 1224Key length (2,3) : 0x0000 1225Extra length (4) : 0x00 1226Data type (5) : 0x00 1227Status (6,7) : 0x0000 1228Total body (8-11) : 0x00000005 1229Opaque (12-15): 0x00000000 1230CAS (16-23): 0x0000000000000000 1231Extras : None 1232Key : None 1233Value : Textual string "1.3.1" 1234 </artwork> 1235 </figure> 1236 </section> 1237 </section> 1238 1239 <section anchor="command-append" title="Append, Prepend" toc="default"> 1240 <t> 1241 <list style="empty"> 1242 <t>MUST NOT have extras.</t> 1243 <t>MUST have key.</t> 1244 <t>MUST have value.</t> 1245 </list> 1246 </t> 1247 1248 <t> 1249 These commands will either append or prepend the specified 1250 value to the requested key. 1251 </t> 1252 1253 <section anchor="command-append-example" title="Example" toc="default"> 1254 <t>The following example appends '!' to the 'Hello' key.</t> 1255 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 1256 <preamble>Append request:</preamble> 1257 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 1258 Byte/ 0 | 1 | 2 | 3 | 1259 / | | | | 1260 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 1261 +---------------+---------------+---------------+---------------+ 1262 0| 0x80 | 0x0e | 0x00 | 0x05 | 1263 +---------------+---------------+---------------+---------------+ 1264 4| 0x00 | 0x00 | 0x00 | 0x00 | 1265 +---------------+---------------+---------------+---------------+ 1266 8| 0x00 | 0x00 | 0x00 | 0x06 | 1267 +---------------+---------------+---------------+---------------+ 1268 12| 0x00 | 0x00 | 0x00 | 0x00 | 1269 +---------------+---------------+---------------+---------------+ 1270 16| 0x00 | 0x00 | 0x00 | 0x00 | 1271 +---------------+---------------+---------------+---------------+ 1272 20| 0x00 | 0x00 | 0x00 | 0x00 | 1273 +---------------+---------------+---------------+---------------+ 1274 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | 1275 +---------------+---------------+---------------+---------------+ 1276 28| 0x6f ('o') | 0x21 ('!') | 1277 +---------------+---------------+ 1278 Total 30 bytes (24 byte header, 5 byte key, 1 byte value) 1279 1280Field (offset) (value) 1281Magic (0) : 0x80 1282Opcode (1) : 0x0e 1283Key length (2,3) : 0x0005 1284Extra length (4) : 0x00 1285Data type (5) : 0x00 1286Reserved (6,7) : 0x0000 1287Total body (8-11) : 0x00000006 1288Opaque (12-15): 0x00000000 1289CAS (16-23): 0x0000000000000000 1290Extras : None 1291Key (24-28): The textual string "Hello" 1292Value (29) : "!" 1293 </artwork> 1294 </figure> 1295 <t> 1296 The response-packet contains no extra data, and the result of the 1297 operation is signaled through the status code. 1298 </t> 1299 </section> 1300 </section> 1301 1302 <section anchor="command-stat" title="Stat" toc="default"> 1303 <t> 1304 <list style="empty"> 1305 <t>MUST NOT have extras.</t> 1306 <t>MAY have key.</t> 1307 <t>MUST NOT have value.</t> 1308 </list> 1309 </t> 1310 1311 <t> 1312 Request server statistics. Without a key specified the server will 1313 respond with a "default" set of statistics information. Each piece 1314 of statistical information is returned in its own packet (key 1315 contains the name of the statistical item and the body contains the 1316 value in ASCII format). The sequence of return packets is terminated 1317 with a packet that contains no key and no value. 1318 </t> 1319 <section anchor="command-stat-example" title="Example" toc="default"> 1320 <t>The following example requests all statistics from the server</t> 1321 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 1322 <preamble>Stat request:</preamble> 1323 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 1324 Byte/ 0 | 1 | 2 | 3 | 1325 / | | | | 1326 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 1327 +---------------+---------------+---------------+---------------+ 1328 0| 0x80 | 0x10 | 0x00 | 0x00 | 1329 +---------------+---------------+---------------+---------------+ 1330 4| 0x00 | 0x00 | 0x00 | 0x00 | 1331 +---------------+---------------+---------------+---------------+ 1332 8| 0x00 | 0x00 | 0x00 | 0x00 | 1333 +---------------+---------------+---------------+---------------+ 1334 12| 0x00 | 0x00 | 0x00 | 0x00 | 1335 +---------------+---------------+---------------+---------------+ 1336 16| 0x00 | 0x00 | 0x00 | 0x00 | 1337 +---------------+---------------+---------------+---------------+ 1338 20| 0x00 | 0x00 | 0x00 | 0x00 | 1339 +---------------+---------------+---------------+---------------+ 1340 Total 24 bytes 1341 1342Field (offset) (value) 1343Magic (0) : 0x80 1344Opcode (1) : 0x10 1345Key length (2,3) : 0x0000 1346Extra length (4) : 0x00 1347Data type (5) : 0x00 1348Reserved (6,7) : 0x0000 1349Total body (8-11) : 0x00000000 1350Opaque (12-15): 0x00000000 1351CAS (16-23): 0x0000000000000000 1352Extras : None 1353Key : None 1354Value : None 1355 </artwork> 1356 </figure> 1357 <t> 1358 The server will send each value in a separate packet with 1359 an "empty" packet (no key / no value) to terminate the sequence. 1360 Each of the response packets look like the following example: 1361 </t> 1362 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 1363 <preamble>Stat response:</preamble> 1364 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 1365 Byte/ 0 | 1 | 2 | 3 | 1366 / | | | | 1367 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 1368 +---------------+---------------+---------------+---------------+ 1369 0| 0x81 | 0x10 | 0x00 | 0x03 | 1370 +---------------+---------------+---------------+---------------+ 1371 4| 0x00 | 0x00 | 0x00 | 0x00 | 1372 +---------------+---------------+---------------+---------------+ 1373 8| 0x00 | 0x00 | 0x00 | 0x07 | 1374 +---------------+---------------+---------------+---------------+ 1375 12| 0x00 | 0x00 | 0x00 | 0x00 | 1376 +---------------+---------------+---------------+---------------+ 1377 16| 0x00 | 0x00 | 0x00 | 0x00 | 1378 +---------------+---------------+---------------+---------------+ 1379 20| 0x00 | 0x00 | 0x00 | 0x00 | 1380 +---------------+---------------+---------------+---------------+ 1381 24| 0x70 ('p') | 0x69 ('i') | 0x64 ('d') | 0x33 ('3') | 1382 +---------------+---------------+---------------+---------------+ 1383 28| 0x30 ('0') | 0x37 ('7') | 0x38 ('8') | 1384 +---------------+---------------+---------------+ 1385 Total 31 bytes (24 byte header, 3 byte key, 4 byte body) 1386 1387Field (offset) (value) 1388Magic (0) : 0x81 1389Opcode (1) : 0x10 1390Key length (2,3) : 0x0003 1391Extra length (4) : 0x00 1392Data type (5) : 0x00 1393Status (6,7) : 0x0000 1394Total body (8-11) : 0x00000007 1395Opaque (12-15): 0x00000000 1396CAS (16-23): 0x0000000000000000 1397Extras : None 1398Key : The textual string "pid" 1399Value : The textual string "3078" 1400 </artwork> 1401 </figure> 1402 </section> 1403 </section> 1404 </section> 1405 <section anchor="security" title="Security Considerations" toc="default"> 1406 <t> 1407 Memcache has few authentication and no security layers whatsoever. It is 1408 RECOMMENDED that memcache be deployed strictly on closed, protected, 1409 back-end networks within a single data center, within a single cluster of 1410 servers, or even on a single host, providing shared caching for multiple 1411 applications. Memcache MUST NOT be made available on a public network. 1412 </t> 1413 1414 <t> 1415 SASL is supported as an authentication mechanism. See the wiki for more 1416 information. 1417 </t> 1418 </section> 1419 1420 </middle> 1421 1422 <back> 1423 <references title="Normative References"> 1424 <reference anchor="LJ" quote-title="true"> 1425 <front> 1426 <title>LJ NEEDS MOAR SPEED</title> 1427 <author fullname="Brad Fitzpatrick"> 1428 <organization>Danga Interactive</organization> 1429 </author> 1430 <date day="5" month="10" year="1999"/> 1431 <abstract> 1432 <t>http://www.livejournal.com/</t> 1433 </abstract> 1434 </front> 1435 </reference> 1436 <reference anchor="KEYWORDS"> 1437 1438<front> 1439<title abbrev="RFC Key Words">Key words for use in RFCs to Indicate Requirement Levels</title> 1440<author initials="S." surname="Bradner" fullname="Scott Bradner"> 1441<organization>Harvard University</organization> 1442<address> 1443<postal> 1444<street>1350 Mass. Ave.</street> 1445<street>Cambridge</street> 1446<street>MA 02138</street></postal> 1447<phone>- +1 617 495 3864</phone> 1448<email>[email protected]</email></address></author> 1449<date year="1997" month="March"/> 1450<area>General</area> 1451<keyword>keyword</keyword> 1452<abstract> 1453<t> 1454 In many standards track documents several words are used to signify 1455 the requirements in the specification. These words are often 1456 capitalized. This document defines these words as they should be 1457 interpreted in IETF documents. Authors who follow these guidelines 1458 should incorporate this phrase near the beginning of their document: 1459 1460<list> 1461<t> 1462 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 1463 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and 1464 "OPTIONAL" in this document are to be interpreted as described in 1465 RFC 2119. 1466</t></list></t> 1467<t> 1468 Note that the force of these words is modified by the requirement 1469 level of the document in which they are used. 1470</t></abstract></front> 1471 1472<seriesInfo name="BCP" value="14"/> 1473<seriesInfo name="RFC" value="2119"/> 1474<format type="TXT" octets="4723" target="http://www.rfc-editor.org/rfc/rfc2119.txt"/> 1475<format type="HTML" octets="17970" target="http://xml.resource.org/public/rfc/html/rfc2119.html"/> 1476<format type="XML" octets="5777" target="http://xml.resource.org/public/rfc/xml/rfc2119.xml"/> 1477</reference> 1478 </references> 1479 1480 <section anchor="acknowledgments" title="Acknowledgments" toc="default"> 1481 <t> 1482 Thanks to Brad Fitzpatrick, Anatoly Vorobey, Steven Grimm, and Dustin 1483 Sallings, for their work on the memcached server. 1484 </t> 1485 1486 <t> 1487 Thanks to Sean Chittenden, Jonathan Steinert, Brian Aker, Evan Martin, 1488 Nathan Neulinger, Eric Hodel, Michael Johnson, Paul Querna, Jamie 1489 McCarthy, Philip Neustrom, Andrew O'Brien, Josh Rotenberg, Robin H. 1490 Johnson, Tim Yardley, Paolo Borelli, Eli Bingham, Jean-Francois 1491 Bustarret, Paul G, Paul Lindner, Alan Kasindorf, Chris Goffinet, Tomash 1492 Brechko, and others for their work reporting bugs and maintaining 1493 memcached client libraries and bindings in many languages. 1494 </t> 1495 </section> 1496 </back> 1497 1498</rfc> 1499