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