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 should 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> 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 the 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 distinguish the nature of the packet from the direction 182 which it is moving. Note, it is common to run a memcached instance on 183 a host that also runs an application server. Such a host will both 184 send 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 large</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 for each request. If the status code of a response 260 packet is non-nil, the body of the packet will contain a textual error 261 message. If the status code is nil, the command opcode will define the 262 layout of the body of the message. 263 </t> 264 <section anchor="command-introduction-example" title="Example"> 265 <t> 266 The following figure illustrates the packet layout for 267 a packet with an error message. 268 </t> 269 <figure> 270 <preamble>Packet layout:</preamble> 271 <artwork> 272 273 Byte/ 0 | 1 | 2 | 3 | 274 / | | | | 275 |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| 276 +---------------+---------------+---------------+---------------+ 277 0| 0x81 | 0x00 | 0x00 | 0x00 | 278 +---------------+---------------+---------------+---------------+ 279 4| 0x00 | 0x00 | 0x00 | 0x01 | 280 +---------------+---------------+---------------+---------------+ 281 8| 0x00 | 0x00 | 0x00 | 0x09 | 282 +---------------+---------------+---------------+---------------+ 283 12| 0x00 | 0x00 | 0x00 | 0x00 | 284 +---------------+---------------+---------------+---------------+ 285 16| 0x00 | 0x00 | 0x00 | 0x00 | 286 +---------------+---------------+---------------+---------------+ 287 20| 0x00 | 0x00 | 0x00 | 0x00 | 288 +---------------+---------------+---------------+---------------+ 289 24| 0x4e ('N') | 0x6f ('o') | 0x74 ('t') | 0x20 (' ') | 290 +---------------+---------------+---------------+---------------+ 291 28| 0x66 ('f') | 0x6f ('o') | 0x75 ('u') | 0x6e ('n') | 292 +---------------+---------------+---------------+---------------+ 293 32| 0x64 ('d') | 294 +---------------+ 295 Total 33 bytes (24 byte header, and 9 bytes value) 296 297Field (offset) (value) 298Magic (0) : 0x81 299Opcode (1) : 0x00 300Key length (2,3) : 0x0000 301Extra length (4) : 0x00 302Data type (5) : 0x00 303Status (6,7) : 0x0001 304Total body (8-11) : 0x00000009 305Opaque (12-15): 0x00000000 306CAS (16-23): 0x0000000000000000 307Extras : None 308Key : None 309Value (24-32): The textual string "Not found" 310 </artwork> 311 </figure> 312 </section> 313 </section> 314 315 <section anchor="command-get" title="Get, Get Quietly, Get Key, Get Key Quietly"> 316 <t> 317 Request: 318 </t> 319 <t> 320 <list style="empty"> 321 <t>MUST NOT have extras.</t> 322 <t>MUST have key.</t> 323 <t>MUST NOT have value.</t> 324 </list> 325 </t> 326 327 <t> 328 <list style="symbols"> 329 <t>4 byte flags</t> 330 </list> 331 </t> 332 333 <t> 334 Response (if found): 335 </t> 336 <t> 337 <list style="empty"> 338 <t>MUST have extras.</t> 339 <t>MAY have key.</t> 340 <t>MAY have value.</t> 341 </list> 342 </t> 343 344 <t> 345 <list style="symbols"> 346 <t>4 byte flags</t> 347 </list> 348 </t> 349 350 <t> 351 <figure> 352 <preamble>Extra data for the get commands:</preamble> 353 <artwork> 354 Byte/ 0 | 1 | 2 | 3 | 355 / | | | | 356 |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| 357 +---------------+---------------+---------------+---------------+ 358 0| Flags | 359 +---------------+---------------+---------------+---------------+ 360 361 Total 4 bytes 362 </artwork> 363 </figure> 364 </t> 365 366 <t> 367 The get command gets a single key. The getq command is both mum 368 on cache miss and quiet, holding its response until a non-quiet 369 command is issued. Getk and getkq differs from get and getq by 370 adding the key into the response packet. 371 </t> 372 373 <t> 374 You're not guaranteed a response to a getq/getkq cache hit until 375 you send a non-getq/getkq command later, which uncorks the 376 server and bundles up IOs to send to the client in one go. 377 </t> 378 379 <t> 380 Clients should implement multi-get (still important for 381 reducing network roundtrips!) as n pipelined requests, the 382 first n-1 being getq/getkq, the last being a regular 383 get/getk. That way you're guaranteed to get a response, and 384 you know when the server's done. You can also do the naive 385 thing and send n pipelined get/getks, but then you could potentially 386 get back a lot of "NOT_FOUND" error code packets. 387 Alternatively, you can send 'n' getq/getkqs, followed by a 388 'noop' command. 389 </t> 390 391 <section anchor="command-get-example" title="Example"> 392 <t> 393 To request the data associated with the key "Hello" the 394 following fields must be specified in the packet. 395 </t> 396 <figure> 397 <preamble>get request:</preamble> 398 <artwork> 399 Byte/ 0 | 1 | 2 | 3 | 400 / | | | | 401 |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| 402 +---------------+---------------+---------------+---------------+ 403 0| 0x80 | 0x00 | 0x00 | 0x05 | 404 +---------------+---------------+---------------+---------------+ 405 4| 0x00 | 0x00 | 0x00 | 0x00 | 406 +---------------+---------------+---------------+---------------+ 407 8| 0x00 | 0x00 | 0x00 | 0x05 | 408 +---------------+---------------+---------------+---------------+ 409 12| 0x00 | 0x00 | 0x00 | 0x00 | 410 +---------------+---------------+---------------+---------------+ 411 16| 0x00 | 0x00 | 0x00 | 0x00 | 412 +---------------+---------------+---------------+---------------+ 413 20| 0x00 | 0x00 | 0x00 | 0x00 | 414 +---------------+---------------+---------------+---------------+ 415 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | 416 +---------------+---------------+---------------+---------------+ 417 28| 0x6f ('o') | 418 +---------------+ 419 420 Total 29 bytes (24 byte header, and 5 bytes key) 421 422Field (offset) (value) 423Magic (0) : 0x80 424Opcode (1) : 0x00 425Key length (2,3) : 0x0005 426Extra length (4) : 0x00 427Data type (5) : 0x00 428Reserved (6,7) : 0x0000 429Total body (8-11) : 0x00000005 430Opaque (12-15): 0x00000000 431CAS (16-23): 0x0000000000000000 432Extras : None 433Key (24-29): The textual string: "Hello" 434Value : None 435 </artwork> 436 </figure> 437 <t>If the item exist on the server the following packet is returned, 438 otherwise a packet with status code != 0 will be returned (see 439 <xref target="command-introduction">Introduction</xref>) 440 </t> 441 <figure> 442 <preamble>get/getq response:</preamble> 443 <artwork> 444 445 Byte/ 0 | 1 | 2 | 3 | 446 / | | | | 447 |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| 448 +---------------+---------------+---------------+---------------+ 449 0| 0x81 | 0x00 | 0x00 | 0x00 | 450 +---------------+---------------+---------------+---------------+ 451 4| 0x04 | 0x00 | 0x00 | 0x00 | 452 +---------------+---------------+---------------+---------------+ 453 8| 0x00 | 0x00 | 0x00 | 0x09 | 454 +---------------+---------------+---------------+---------------+ 455 12| 0x00 | 0x00 | 0x00 | 0x00 | 456 +---------------+---------------+---------------+---------------+ 457 16| 0x00 | 0x00 | 0x00 | 0x00 | 458 +---------------+---------------+---------------+---------------+ 459 20| 0x00 | 0x00 | 0x00 | 0x01 | 460 +---------------+---------------+---------------+---------------+ 461 24| 0xde | 0xad | 0xbe | 0xef | 462 +---------------+---------------+---------------+---------------+ 463 28| 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | 0x6c ('l') | 464 +---------------+---------------+---------------+---------------+ 465 32| 0x64 ('d') | 466 +---------------+ 467 468 Total 33 bytes (24 byte header, 4 byte extras and 5 byte value) 469 470Field (offset) (value) 471Magic (0) : 0x81 472Opcode (1) : 0x00 473Key length (2,3) : 0x0000 474Extra length (4) : 0x04 475Data type (5) : 0x00 476Status (6,7) : 0x0000 477Total body (8-11) : 0x00000009 478Opaque (12-15): 0x00000000 479CAS (16-23): 0x0000000000000001 480Extras : 481 Flags (24-27): 0xdeadbeef 482Key : None 483Value (28-32): The textual string "World" 484 </artwork> 485 </figure> 486 <figure> 487 <preamble>getk/getkq response:</preamble> 488 <artwork> 489 490 Byte/ 0 | 1 | 2 | 3 | 491 / | | | | 492 |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| 493 +---------------+---------------+---------------+---------------+ 494 0| 0x81 | 0x00 | 0x00 | 0x05 | 495 +---------------+---------------+---------------+---------------+ 496 4| 0x04 | 0x00 | 0x00 | 0x00 | 497 +---------------+---------------+---------------+---------------+ 498 8| 0x00 | 0x00 | 0x00 | 0x09 | 499 +---------------+---------------+---------------+---------------+ 500 12| 0x00 | 0x00 | 0x00 | 0x00 | 501 +---------------+---------------+---------------+---------------+ 502 16| 0x00 | 0x00 | 0x00 | 0x00 | 503 +---------------+---------------+---------------+---------------+ 504 20| 0x00 | 0x00 | 0x00 | 0x01 | 505 +---------------+---------------+---------------+---------------+ 506 24| 0xde | 0xad | 0xbe | 0xef | 507 +---------------+---------------+---------------+---------------+ 508 28| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | 509 +---------------+---------------+---------------+---------------+ 510 32| 0x6f ('o') | 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | 511 +---------------+---------------+---------------+---------------+ 512 36| 0x6c ('l') | 0x64 ('d') | 513 +---------------+---------------+ 514 515 Total 38 bytes (24 byte header, 4 byte extras, 5 byte key 516 and 5 byte value) 517 518Field (offset) (value) 519Magic (0) : 0x81 520Opcode (1) : 0x00 521Key length (2,3) : 0x0005 522Extra length (4) : 0x04 523Data type (5) : 0x00 524Status (6,7) : 0x0000 525Total body (8-11) : 0x00000009 526Opaque (12-15): 0x00000000 527CAS (16-23): 0x0000000000000001 528Extras : 529 Flags (24-27): 0xdeadbeef 530Key (28-32): The textual string: "Hello" 531Value (33-37): The textual string: "World" 532 </artwork> 533 </figure> 534 </section> 535 </section> 536 537 <section anchor="command-set" title="Set, Add, Replace"> 538 <t> 539 <list style="empty"> 540 <t>MUST have extras.</t> 541 <t>MUST have key.</t> 542 <t>MUST have value.</t> 543 </list> 544 </t> 545 546 <t> 547 <list style="symbols"> 548 <t>4 byte flags</t> 549 <t>4 byte expiration time</t> 550 </list> 551 </t> 552 553 <figure> 554 <preamble>Extra data for set/add/replace:</preamble> 555 <artwork> 556 Byte/ 0 | 1 | 2 | 3 | 557 / | | | | 558 |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| 559 +---------------+---------------+---------------+---------------+ 560 0| Flags | 561 +---------------+---------------+---------------+---------------+ 562 4| Expiration | 563 +---------------+---------------+---------------+---------------+ 564 Total 8 bytes 565 </artwork> 566 </figure> 567 568 <t> 569 If the Data Version Check (CAS) is nonzero, the requested 570 operation MUST only succeed if the item exists and has a CAS value 571 identical to the provided value. 572 </t> 573 574 <t> 575 Add MUST fail if the item already exist. 576 </t> 577 578 <t> 579 Replace MUST fail if the item doesn't exist. 580 </t> 581 582 <t> 583 Set should store the data unconditionally if the item exists 584 or not. 585 </t> 586 587 <section anchor="command-set-example" title="Example"> 588 <t>The following figure shows an add-command for 589 <list style="empty"> 590 <t>Key: "Hello"</t> 591 <t>Value: "World"</t> 592 <t>Flags: 0xdeadbeef</t> 593 <t>Expiry: in two hours</t> 594 </list> 595 </t> 596 <figure> 597 <preamble>Add request:</preamble> 598 <artwork> 599 600 Byte/ 0 | 1 | 2 | 3 | 601 / | | | | 602 |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| 603 +---------------+---------------+---------------+---------------+ 604 0| 0x80 | 0x02 | 0x00 | 0x05 | 605 +---------------+---------------+---------------+---------------+ 606 4| 0x08 | 0x00 | 0x00 | 0x00 | 607 +---------------+---------------+---------------+---------------+ 608 8| 0x00 | 0x00 | 0x00 | 0x12 | 609 +---------------+---------------+---------------+---------------+ 610 12| 0x00 | 0x00 | 0x00 | 0x00 | 611 +---------------+---------------+---------------+---------------+ 612 16| 0x00 | 0x00 | 0x00 | 0x00 | 613 +---------------+---------------+---------------+---------------+ 614 20| 0x00 | 0x00 | 0x00 | 0x00 | 615 +---------------+---------------+---------------+---------------+ 616 24| 0xde | 0xad | 0xbe | 0xef | 617 +---------------+---------------+---------------+---------------+ 618 28| 0x00 | 0x00 | 0x0e | 0x10 | 619 +---------------+---------------+---------------+---------------+ 620 32| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | 621 +---------------+---------------+---------------+---------------+ 622 36| 0x6f ('o') | 0x57 ('W') | 0x6f ('o') | 0x72 ('r') | 623 +---------------+---------------+---------------+---------------+ 624 40| 0x6c ('l') | 0x64 ('d') | 625 +---------------+---------------+ 626 627 Total 42 bytes (24 byte header, 8 byte extras, 5 byte key and 628 5 byte value) 629 630Field (offset) (value) 631Magic (0) : 0x80 632Opcode (1) : 0x02 633Key length (2,3) : 0x0005 634Extra length (4) : 0x08 635Data type (5) : 0x00 636Reserved (6,7) : 0x0000 637Total body (8-11) : 0x00000012 638Opaque (12-15): 0x00000000 639CAS (16-23): 0x0000000000000000 640Extras : 641 Flags (24-27): 0xdeadbeef 642 Expiry (28-31): 0x00000e10 643Key (32-36): The textual string "Hello" 644Value (37-41): The textual string "World" 645 </artwork> 646 </figure> 647 <t> 648 The response-packet contains no extra data, and the result of the 649 operation is signaled through the status code. If the command 650 succeeds, the CAS value for the item is returned in the CAS-field 651 of the packet. 652 </t> 653 <figure> 654 <preamble>Successful add response:</preamble> 655 <artwork> 656 657 Byte/ 0 | 1 | 2 | 3 | 658 / | | | | 659 |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| 660 +---------------+---------------+---------------+---------------+ 661 0| 0x81 | 0x02 | 0x00 | 0x00 | 662 +---------------+---------------+---------------+---------------+ 663 4| 0x00 | 0x00 | 0x00 | 0x00 | 664 +---------------+---------------+---------------+---------------+ 665 8| 0x00 | 0x00 | 0x00 | 0x00 | 666 +---------------+---------------+---------------+---------------+ 667 12| 0x00 | 0x00 | 0x00 | 0x00 | 668 +---------------+---------------+---------------+---------------+ 669 16| 0x00 | 0x00 | 0x00 | 0x00 | 670 +---------------+---------------+---------------+---------------+ 671 20| 0x00 | 0x00 | 0x00 | 0x01 | 672 +---------------+---------------+---------------+---------------+ 673 674 Total 24 bytes 675 676Field (offset) (value) 677Magic (0) : 0x81 678Opcode (1) : 0x02 679Key length (2,3) : 0x0000 680Extra length (4) : 0x00 681Data type (5) : 0x00 682Status (6,7) : 0x0000 683Total body (8-11) : 0x00000000 684Opaque (12-15): 0x00000000 685CAS (16-23): 0x0000000000000001 686Extras : None 687Key : None 688Value : None 689 </artwork> 690 </figure> 691 </section> 692 </section> 693 694 <section anchor="command-delete" title="Delete"> 695 <t> 696 <list style="empty"> 697 <t>MUST NOT have extras.</t> 698 <t>MUST have key.</t> 699 <t>MUST NOT have value.</t> 700 </list> 701 </t> 702 703 <t> 704 Delete the item with the specific key. 705 </t> 706 707 <section anchor="command-delete-example" title="Example"> 708 <t>The following figure shows a delete message for the 709 item "Hello".</t> 710 <figure> 711 <preamble>Delete request:</preamble> 712 <artwork> 713 Byte/ 0 | 1 | 2 | 3 | 714 / | | | | 715 |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| 716 +---------------+---------------+---------------+---------------+ 717 0| 0x80 | 0x04 | 0x00 | 0x05 | 718 +---------------+---------------+---------------+---------------+ 719 4| 0x00 | 0x00 | 0x00 | 0x00 | 720 +---------------+---------------+---------------+---------------+ 721 8| 0x00 | 0x00 | 0x00 | 0x05 | 722 +---------------+---------------+---------------+---------------+ 723 12| 0x00 | 0x00 | 0x00 | 0x00 | 724 +---------------+---------------+---------------+---------------+ 725 16| 0x00 | 0x00 | 0x00 | 0x00 | 726 +---------------+---------------+---------------+---------------+ 727 20| 0x00 | 0x00 | 0x00 | 0x00 | 728 +---------------+---------------+---------------+---------------+ 729 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | 730 +---------------+---------------+---------------+---------------+ 731 28| 0x6f ('o') | 732 +---------------+ 733 734 Total 29 bytes (24 byte header, 5 byte value) 735 736Field (offset) (value) 737Magic (0) : 0x80 738Opcode (1) : 0x04 739Key length (2,3) : 0x0005 740Extra length (4) : 0x00 741Data type (5) : 0x00 742Reserved (6,7) : 0x0000 743Total body (8-11) : 0x00000005 744Opaque (12-15): 0x00000000 745CAS (16-23): 0x0000000000000000 746Extras : None 747Key : The textual string "Hello" 748Value : None 749 </artwork> 750 </figure> 751 <t> 752 The response-packet contains no extra data, and the result of the 753 operation is signaled through the status code. 754 </t> 755 </section> 756 </section> 757 758 <section anchor="command-incr" title="Increment, Decrement"> 759 <t> 760 <list style="empty"> 761 <t>MUST have extras.</t> 762 <t>MUST have key.</t> 763 <t>MUST NOT have value.</t> 764 </list> 765 </t> 766 767 <t> 768 <list style="symbols"> 769 <t>8 byte value to add / subtract</t> 770 <t>8 byte initial value (unsigned)</t> 771 <t>4 byte expiration time</t> 772 </list> 773 </t> 774 <figure> 775 <preamble>Extra data for incr/decr:</preamble> 776 <artwork> 777 Byte/ 0 | 1 | 2 | 3 | 778 / | | | | 779 |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| 780 +---------------+---------------+---------------+---------------+ 781 0| Amount to add | 782 | | 783 +---------------+---------------+---------------+---------------+ 784 8| Initial value | 785 | | 786 +---------------+---------------+---------------+---------------+ 787 16| Expiration | 788 +---------------+---------------+---------------+---------------+ 789 Total 20 bytes 790 </artwork> 791 </figure> 792 793 <t> 794 These commands will either add or remove the specified 795 amount to the requested counter. 796 </t> 797 <t> 798 If the counter does not exist, one of two things may happen: 799 </t> 800 <t> 801 <list style="numbers"> 802 <t>If the expiration value is all one-bits (0xffffffff), the 803 operation will fail with NOT_FOUND.</t> 804 <t>For all other expiration values, the operation will succeed 805 by seeding the value for this key with the provided initial 806 value to expire with the provided expiration time. The flags 807 will be set to zero.</t> 808 </list> 809 </t> 810 <figure> 811 <preamble>incr/decr response body:</preamble> 812 <artwork> 813 Byte/ 0 | 1 | 2 | 3 | 814 / | | | | 815 |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| 816 +---------------+---------------+---------------+---------------+ 817 0| 64-bit unsigned response. | 818 | | 819 +---------------+---------------+---------------+---------------+ 820 Total 8 bytes 821 </artwork> 822 </figure> 823 <section anchor="command-incr-example" title="Example"> 824 <t>The following figure shows an incr-command for 825 <list style="empty"> 826 <t>Key: "counter"</t> 827 <t>Delta: 0x01</t> 828 <t>Initial: 0x00</t> 829 <t>Expiry: in two hours</t> 830 </list> 831 </t> 832 <figure> 833 <preamble>Increment request:</preamble> 834 <artwork> 835 836 Byte/ 0 | 1 | 2 | 3 | 837 / | | | | 838 |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| 839 +---------------+---------------+---------------+---------------+ 840 0| 0x80 | 0x05 | 0x00 | 0x07 | 841 +---------------+---------------+---------------+---------------+ 842 4| 0x14 | 0x00 | 0x00 | 0x00 | 843 +---------------+---------------+---------------+---------------+ 844 8| 0x00 | 0x00 | 0x00 | 0x1b | 845 +---------------+---------------+---------------+---------------+ 846 12| 0x00 | 0x00 | 0x00 | 0x00 | 847 +---------------+---------------+---------------+---------------+ 848 16| 0x00 | 0x00 | 0x00 | 0x00 | 849 +---------------+---------------+---------------+---------------+ 850 20| 0x00 | 0x00 | 0x00 | 0x00 | 851 +---------------+---------------+---------------+---------------+ 852 24| 0x00 | 0x00 | 0x00 | 0x00 | 853 +---------------+---------------+---------------+---------------+ 854 28| 0x00 | 0x00 | 0x00 | 0x01 | 855 +---------------+---------------+---------------+---------------+ 856 32| 0x00 | 0x00 | 0x00 | 0x00 | 857 +---------------+---------------+---------------+---------------+ 858 36| 0x00 | 0x00 | 0x00 | 0x00 | 859 +---------------+---------------+---------------+---------------+ 860 40| 0x00 | 0x00 | 0x0e | 0x10 | 861 +---------------+---------------+---------------+---------------+ 862 44| 0x63 ('c') | 0x6f ('o') | 0x75 ('u') | 0x6e ('n') | 863 +---------------+---------------+---------------+---------------+ 864 48| 0x74 ('t') | 0x65 ('e') | 0x72 ('r') | 865 +---------------+---------------+---------------+ 866 Total 51 bytes (24 byte header, 20 byte extras, 7 byte key) 867 868Field (offset) (value) 869Magic (0) : 0x80 870Opcode (1) : 0x05 871Key length (2,3) : 0x0007 872Extra length (4) : 0x14 873Data type (5) : 0x00 874Reserved (6,7) : 0x0000 875Total body (8-11) : 0x0000001b 876Opaque (12-15): 0x00000000 877CAS (16-23): 0x0000000000000000 878Extras : 879 delta (24-31): 0x0000000000000001 880 initial (32-39): 0x0000000000000000 881 exipration (40-43): 0x00000e10 882Key : Textual string "counter" 883Value : None 884 </artwork> 885 </figure> 886 <t> 887 If the key doesn't exist, the server will respond with the 888 initial value. If not the incremented value will be returned. 889 Let's assume that the key didn't exist, so the initial value 890 is returned. 891 </t> 892 <figure> 893 <preamble>Increment response:</preamble> 894 <artwork> 895 Byte/ 0 | 1 | 2 | 3 | 896 / | | | | 897 |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| 898 +---------------+---------------+---------------+---------------+ 899 0| 0x81 | 0x05 | 0x00 | 0x00 | 900 +---------------+---------------+---------------+---------------+ 901 4| 0x00 | 0x00 | 0x00 | 0x00 | 902 +---------------+---------------+---------------+---------------+ 903 8| 0x00 | 0x00 | 0x00 | 0x08 | 904 +---------------+---------------+---------------+---------------+ 905 12| 0x00 | 0x00 | 0x00 | 0x00 | 906 +---------------+---------------+---------------+---------------+ 907 16| 0x00 | 0x00 | 0x00 | 0x00 | 908 +---------------+---------------+---------------+---------------+ 909 20| 0x00 | 0x00 | 0x00 | 0x05 | 910 +---------------+---------------+---------------+---------------+ 911 24| 0x00 | 0x00 | 0x00 | 0x00 | 912 +---------------+---------------+---------------+---------------+ 913 28| 0x00 | 0x00 | 0x00 | 0x00 | 914 +---------------+---------------+---------------+---------------+ 915 Total 32 bytes (24 byte header, 8 byte value) 916 917Field (offset) (value) 918Magic (0) : 0x81 919Opcode (1) : 0x05 920Key length (2,3) : 0x0000 921Extra length (4) : 0x00 922Data type (5) : 0x00 923Status (6,7) : 0x0000 924Total body (8-11) : 0x00000008 925Opaque (12-15): 0x00000000 926CAS (16-23): 0x0000000000000005 927Extras : None 928Key : None 929Value : 0x0000000000000000 930 </artwork> 931 </figure> 932 </section> 933 </section> 934 935 <section anchor="command-quit" title="quit"> 936 <t> 937 <list style="empty"> 938 <t>MUST NOT have extras.</t> 939 <t>MUST NOT have key.</t> 940 <t>MUST NOT have value.</t> 941 </list> 942 </t> 943 944 <t> 945 Close the connection to the server. 946 </t> 947 948 <section anchor="command-quit-example" title="Example"> 949 <figure> 950 <preamble>Quit request:</preamble> 951 <artwork> 952 Byte/ 0 | 1 | 2 | 3 | 953 / | | | | 954 |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| 955 +---------------+---------------+---------------+---------------+ 956 0| 0x80 | 0x07 | 0x00 | 0x00 | 957 +---------------+---------------+---------------+---------------+ 958 4| 0x00 | 0x00 | 0x00 | 0x00 | 959 +---------------+---------------+---------------+---------------+ 960 8| 0x00 | 0x00 | 0x00 | 0x00 | 961 +---------------+---------------+---------------+---------------+ 962 12| 0x00 | 0x00 | 0x00 | 0x00 | 963 +---------------+---------------+---------------+---------------+ 964 16| 0x00 | 0x00 | 0x00 | 0x00 | 965 +---------------+---------------+---------------+---------------+ 966 20| 0x00 | 0x00 | 0x00 | 0x00 | 967 +---------------+---------------+---------------+---------------+ 968 Total 24 bytes 969 970Field (offset) (value) 971Magic (0) : 0x80 972Opcode (1) : 0x07 973Key length (2,3) : 0x0000 974Extra length (4) : 0x00 975Data type (5) : 0x00 976Reserved (6,7) : 0x0000 977Total body (8-11) : 0x00000000 978Opaque (12-15): 0x00000000 979CAS (16-23): 0x0000000000000000 980Extras : None 981Key : None 982Value : None 983 </artwork> 984 </figure> 985 <t> 986 The response-packet contains no extra data, and the result of the 987 operation is signaled through the status code. The server will 988 then close the connection. 989 </t> 990 </section> 991 </section> 992 993 <section anchor="command-flush" title="Flush"> 994 <t> 995 <list style="empty"> 996 <t>MAY have extras.</t> 997 <t>MUST NOT have key.</t> 998 <t>MUST NOT have value.</t> 999 </list> 1000 </t> 1001 1002 <t> 1003 <list style="symbols"> 1004 <t>4 byte expiration time</t> 1005 </list> 1006 </t> 1007 <figure> 1008 <preamble>Extra data for flush:</preamble> 1009 <artwork> 1010 Byte/ 0 | 1 | 2 | 3 | 1011 / | | | | 1012 |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| 1013 +---------------+---------------+---------------+---------------+ 1014 0| Expiration | 1015 +---------------+---------------+---------------+---------------+ 1016 Total 4 bytes 1017 </artwork> 1018 </figure> 1019 <t> 1020 Flush the items in the cache now or some time in the future as 1021 specified by the expiration field. See the documentation of the 1022 textual protocol for the full description on how to specify the 1023 expiration time. 1024 </t> 1025 <section anchor="command-flush-example" title="Example"> 1026 <t> 1027 To flush the cache (delete all items) in two hours, the set 1028 the following values in the request 1029 </t> 1030 <figure> 1031 <preamble>Flush request:</preamble> 1032 <artwork> 1033 Byte/ 0 | 1 | 2 | 3 | 1034 / | | | | 1035 |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| 1036 +---------------+---------------+---------------+---------------+ 1037 0| 0x80 | 0x08 | 0x00 | 0x00 | 1038 +---------------+---------------+---------------+---------------+ 1039 4| 0x04 | 0x00 | 0x00 | 0x00 | 1040 +---------------+---------------+---------------+---------------+ 1041 8| 0x00 | 0x00 | 0x00 | 0x04 | 1042 +---------------+---------------+---------------+---------------+ 1043 12| 0x00 | 0x00 | 0x00 | 0x00 | 1044 +---------------+---------------+---------------+---------------+ 1045 16| 0x00 | 0x00 | 0x00 | 0x00 | 1046 +---------------+---------------+---------------+---------------+ 1047 20| 0x00 | 0x00 | 0x00 | 0x00 | 1048 +---------------+---------------+---------------+---------------+ 1049 24| 0x00 | 0x00 | 0x0e | 0x10 | 1050 +---------------+---------------+---------------+---------------+ 1051 Total 28 bytes (24 byte header, 4 byte body) 1052 1053Field (offset) (value) 1054Magic (0) : 0x80 1055Opcode (1) : 0x08 1056Key length (2,3) : 0x0000 1057Extra length (4) : 0x04 1058Data type (5) : 0x00 1059Reserved (6,7) : 0x0000 1060Total body (8-11) : 0x00000004 1061Opaque (12-15): 0x00000000 1062CAS (16-23): 0x0000000000000000 1063Extras : 1064 Expiry (24-27): 0x000e10 1065Key : None 1066Value : None 1067 </artwork> 1068 </figure> 1069 <t> 1070 The response-packet contains no extra data, and the result of the 1071 operation is signaled through the status code. 1072 </t> 1073 </section> 1074 </section> 1075 <section anchor="command-noop" title="noop"> 1076 <t> 1077 <list style="empty"> 1078 <t>MUST NOT have extras.</t> 1079 <t>MUST NOT have key.</t> 1080 <t>MUST NOT have value.</t> 1081 </list> 1082 </t> 1083 1084 <t> 1085 Used as a keep alive. Flushes outstanding getq/getkq's. 1086 </t> 1087 <section anchor="command-noop-example" title="Example"> 1088 <figure> 1089 <preamble>Noop request:</preamble> 1090 <artwork> 1091 Byte/ 0 | 1 | 2 | 3 | 1092 / | | | | 1093 |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| 1094 +---------------+---------------+---------------+---------------+ 1095 0| 0x80 | 0x0a | 0x00 | 0x00 | 1096 +---------------+---------------+---------------+---------------+ 1097 4| 0x00 | 0x00 | 0x00 | 0x00 | 1098 +---------------+---------------+---------------+---------------+ 1099 8| 0x00 | 0x00 | 0x00 | 0x00 | 1100 +---------------+---------------+---------------+---------------+ 1101 12| 0x00 | 0x00 | 0x00 | 0x00 | 1102 +---------------+---------------+---------------+---------------+ 1103 16| 0x00 | 0x00 | 0x00 | 0x00 | 1104 +---------------+---------------+---------------+---------------+ 1105 20| 0x00 | 0x00 | 0x00 | 0x00 | 1106 +---------------+---------------+---------------+---------------+ 1107 Total 24 bytes 1108 1109Field (offset) (value) 1110Magic (0) : 0x80 1111Opcode (1) : 0x0a 1112Key length (2,3) : 0x0000 1113Extra length (4) : 0x00 1114Data type (5) : 0x00 1115Reserved (6,7) : 0x0000 1116Total body (8-11) : 0x00000000 1117Opaque (12-15): 0x00000000 1118CAS (16-23): 0x0000000000000000 1119Extras : None 1120Key : None 1121Value : None 1122 </artwork> 1123 </figure> 1124 <t> 1125 The response-packet contains no extra data, and the result of the 1126 operation is signaled through the status code. 1127 </t> 1128 </section> 1129 </section> 1130 1131 <section anchor="command-version" title="version"> 1132 <t> 1133 <list style="empty"> 1134 <t>MUST NOT have extras.</t> 1135 <t>MUST NOT have key.</t> 1136 <t>MUST NOT have value.</t> 1137 </list> 1138 </t> 1139 1140 <t> 1141 Request the server version. 1142 </t> 1143 <t> 1144 The server responds with a packet containing the version string 1145 in the body with the following format: "x.y.z" 1146 </t> 1147 <section anchor="command-version-example" title="Example"> 1148 <figure> 1149 <preamble>Version request:</preamble> 1150 <artwork> 1151 Byte/ 0 | 1 | 2 | 3 | 1152 / | | | | 1153 |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| 1154 +---------------+---------------+---------------+---------------+ 1155 0| 0x80 | 0x0b | 0x00 | 0x00 | 1156 +---------------+---------------+---------------+---------------+ 1157 4| 0x00 | 0x00 | 0x00 | 0x00 | 1158 +---------------+---------------+---------------+---------------+ 1159 8| 0x00 | 0x00 | 0x00 | 0x00 | 1160 +---------------+---------------+---------------+---------------+ 1161 12| 0x00 | 0x00 | 0x00 | 0x00 | 1162 +---------------+---------------+---------------+---------------+ 1163 16| 0x00 | 0x00 | 0x00 | 0x00 | 1164 +---------------+---------------+---------------+---------------+ 1165 20| 0x00 | 0x00 | 0x00 | 0x00 | 1166 +---------------+---------------+---------------+---------------+ 1167 Total 24 bytes 1168 1169Field (offset) (value) 1170Magic (0) : 0x80 1171Opcode (1) : 0x0b 1172Key length (2,3) : 0x0000 1173Extra length (4) : 0x00 1174Data type (5) : 0x00 1175Reserved (6,7) : 0x0000 1176Total body (8-11) : 0x00000000 1177Opaque (12-15): 0x00000000 1178CAS (16-23): 0x0000000000000000 1179Extras : None 1180 </artwork> 1181 </figure> 1182 <figure> 1183 <preamble>Version response:</preamble> 1184 <artwork> 1185 Byte/ 0 | 1 | 2 | 3 | 1186 / | | | | 1187 |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| 1188 +---------------+---------------+---------------+---------------+ 1189 0| 0x81 | 0x0b | 0x00 | 0x00 | 1190 +---------------+---------------+---------------+---------------+ 1191 4| 0x00 | 0x00 | 0x00 | 0x00 | 1192 +---------------+---------------+---------------+---------------+ 1193 8| 0x00 | 0x00 | 0x00 | 0x05 | 1194 +---------------+---------------+---------------+---------------+ 1195 12| 0x00 | 0x00 | 0x00 | 0x00 | 1196 +---------------+---------------+---------------+---------------+ 1197 16| 0x00 | 0x00 | 0x00 | 0x00 | 1198 +---------------+---------------+---------------+---------------+ 1199 20| 0x00 | 0x00 | 0x00 | 0x00 | 1200 +---------------+---------------+---------------+---------------+ 1201 24| 0x31 ('1') | 0x2e ('.') | 0x33 ('3') | 0x2e ('.') | 1202 +---------------+---------------+---------------+---------------+ 1203 28| 0x31 ('1') | 1204 +---------------+ 1205 Total 29 bytes (24 byte header, 5 byte body) 1206 1207Field (offset) (value) 1208Magic (0) : 0x81 1209Opcode (1) : 0x0b 1210Key length (2,3) : 0x0000 1211Extra length (4) : 0x00 1212Data type (5) : 0x00 1213Status (6,7) : 0x0000 1214Total body (8-11) : 0x00000005 1215Opaque (12-15): 0x00000000 1216CAS (16-23): 0x0000000000000000 1217Extras : None 1218Key : None 1219Value : Textual string "1.3.1" 1220 </artwork> 1221 </figure> 1222 </section> 1223 </section> 1224 1225 <section anchor="command-append" title="Append, Prepend"> 1226 <t> 1227 <list style="empty"> 1228 <t>MUST NOT have extras.</t> 1229 <t>MUST have key.</t> 1230 <t>MUST have value.</t> 1231 </list> 1232 </t> 1233 1234 <t> 1235 These commands will either append or prepend the specified 1236 value to the requested key. 1237 </t> 1238 1239 <section anchor="command-append-example" title="Example"> 1240 <t>The following example appends '!' to the 'Hello' key.</t> 1241 <figure> 1242 <preamble>Append request:</preamble> 1243 <artwork> 1244 Byte/ 0 | 1 | 2 | 3 | 1245 / | | | | 1246 |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| 1247 +---------------+---------------+---------------+---------------+ 1248 0| 0x80 | 0x0e | 0x00 | 0x05 | 1249 +---------------+---------------+---------------+---------------+ 1250 4| 0x00 | 0x00 | 0x00 | 0x00 | 1251 +---------------+---------------+---------------+---------------+ 1252 8| 0x00 | 0x00 | 0x00 | 0x06 | 1253 +---------------+---------------+---------------+---------------+ 1254 12| 0x00 | 0x00 | 0x00 | 0x00 | 1255 +---------------+---------------+---------------+---------------+ 1256 16| 0x00 | 0x00 | 0x00 | 0x00 | 1257 +---------------+---------------+---------------+---------------+ 1258 20| 0x00 | 0x00 | 0x00 | 0x00 | 1259 +---------------+---------------+---------------+---------------+ 1260 24| 0x48 ('H') | 0x65 ('e') | 0x6c ('l') | 0x6c ('l') | 1261 +---------------+---------------+---------------+---------------+ 1262 28| 0x6f ('o') | 0x21 ('!') | 1263 +---------------+---------------+ 1264 Total 30 bytes (24 byte header, 5 byte key, 1 byte value) 1265 1266Field (offset) (value) 1267Magic (0) : 0x80 1268Opcode (1) : 0x0e 1269Key length (2,3) : 0x0005 1270Extra length (4) : 0x00 1271Data type (5) : 0x00 1272Reserved (6,7) : 0x0000 1273Total body (8-11) : 0x00000006 1274Opaque (12-15): 0x00000000 1275CAS (16-23): 0x0000000000000000 1276Extras : None 1277Key (24-28): The textual string "Hello" 1278Value (29) : "!" 1279 </artwork> 1280 </figure> 1281 <t> 1282 The response-packet contains no extra data, and the result of the 1283 operation is signaled through the status code. 1284 </t> 1285 </section> 1286 </section> 1287 1288 <section anchor="command-stat" title="Stat"> 1289 <t> 1290 <list style="empty"> 1291 <t>MUST NOT have extras.</t> 1292 <t>MAY have key.</t> 1293 <t>MUST NOT have value.</t> 1294 </list> 1295 </t> 1296 1297 <t> 1298 Request server statistics. Without a key specified the server will 1299 respond with a "default" set of statistics information. Each piece 1300 of statistical information is returned in its own packet (key 1301 contains the name of the statistical item and the body contains the 1302 value in ASCII format). The sequence of return packets is terminated 1303 with a packet that contains no key and no value. 1304 </t> 1305 <section anchor="command-stat-example" title="Example"> 1306 <t>The following example requests all statistics from the server</t> 1307 <figure> 1308 <preamble>Stat request:</preamble> 1309 <artwork> 1310 Byte/ 0 | 1 | 2 | 3 | 1311 / | | | | 1312 |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| 1313 +---------------+---------------+---------------+---------------+ 1314 0| 0x80 | 0x10 | 0x00 | 0x00 | 1315 +---------------+---------------+---------------+---------------+ 1316 4| 0x00 | 0x00 | 0x00 | 0x00 | 1317 +---------------+---------------+---------------+---------------+ 1318 8| 0x00 | 0x00 | 0x00 | 0x00 | 1319 +---------------+---------------+---------------+---------------+ 1320 12| 0x00 | 0x00 | 0x00 | 0x00 | 1321 +---------------+---------------+---------------+---------------+ 1322 16| 0x00 | 0x00 | 0x00 | 0x00 | 1323 +---------------+---------------+---------------+---------------+ 1324 20| 0x00 | 0x00 | 0x00 | 0x00 | 1325 +---------------+---------------+---------------+---------------+ 1326 Total 24 bytes 1327 1328Field (offset) (value) 1329Magic (0) : 0x80 1330Opcode (1) : 0x10 1331Key length (2,3) : 0x0000 1332Extra length (4) : 0x00 1333Data type (5) : 0x00 1334Reserved (6,7) : 0x0000 1335Total body (8-11) : 0x00000000 1336Opaque (12-15): 0x00000000 1337CAS (16-23): 0x0000000000000000 1338Extras : None 1339Key : None 1340Value : None 1341 </artwork> 1342 </figure> 1343 <t> 1344 The server will send each value in a separate packet with 1345 an "empty" packet (no key / no value) to terminate the sequence. 1346 Each of the response packets look like the following example: 1347 </t> 1348 <figure> 1349 <preamble>Stat response:</preamble> 1350 <artwork> 1351 Byte/ 0 | 1 | 2 | 3 | 1352 / | | | | 1353 |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| 1354 +---------------+---------------+---------------+---------------+ 1355 0| 0x81 | 0x10 | 0x00 | 0x03 | 1356 +---------------+---------------+---------------+---------------+ 1357 4| 0x00 | 0x00 | 0x00 | 0x00 | 1358 +---------------+---------------+---------------+---------------+ 1359 8| 0x00 | 0x00 | 0x00 | 0x07 | 1360 +---------------+---------------+---------------+---------------+ 1361 12| 0x00 | 0x00 | 0x00 | 0x00 | 1362 +---------------+---------------+---------------+---------------+ 1363 16| 0x00 | 0x00 | 0x00 | 0x00 | 1364 +---------------+---------------+---------------+---------------+ 1365 20| 0x00 | 0x00 | 0x00 | 0x00 | 1366 +---------------+---------------+---------------+---------------+ 1367 24| 0x70 ('p') | 0x69 ('i') | 0x64 ('d') | 0x33 ('3') | 1368 +---------------+---------------+---------------+---------------+ 1369 28| 0x30 ('0') | 0x37 ('7') | 0x38 ('8') | 1370 +---------------+---------------+---------------+ 1371 Total 31 bytes (24 byte header, 3 byte key, 4 byte body) 1372 1373Field (offset) (value) 1374Magic (0) : 0x81 1375Opcode (1) : 0x10 1376Key length (2,3) : 0x0003 1377Extra length (4) : 0x00 1378Data type (5) : 0x00 1379Status (6,7) : 0x0000 1380Total body (8-11) : 0x00000007 1381Opaque (12-15): 0x00000000 1382CAS (16-23): 0x0000000000000000 1383Exstras : None 1384Key : The textual string "pid" 1385Value : The textual string "3078" 1386 </artwork> 1387 </figure> 1388 </section> 1389 </section> 1390 </section> 1391 <section anchor="security" title="Security Considerations"> 1392 <t> 1393 Memcache has no authentication or security layers whatsoever. It is 1394 RECOMMENDED that memcache be deployed strictly on closed, protected, 1395 back-end networks within a single data center, within a single cluster of 1396 servers, or even on a single host, providing shared caching for multiple 1397 applications. Memcache MUST NOT be made available on a public network. 1398 </t> 1399 </section> 1400 1401 </middle> 1402 1403 <back> 1404 <references title="Normative References"> 1405 <reference anchor="LJ"> 1406 <front> 1407 <title>LJ NEEDS MOAR SPEED</title> 1408 <author fullname="Brad Fitzpatrick"> 1409 <organization>Danga Interactive</organization> 1410 </author> 1411 <date day="5" month="10" year="1999" /> 1412 <abstract> 1413 <t>http://www.livejournal.com/</t> 1414 </abstract> 1415 </front> 1416 </reference> 1417 <dwdrfc-ref anchor="KEYWORDS" src='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'/> 1418 </references> 1419 1420 <section anchor="acknowledgments" title="Acknowledgments"> 1421 <t> 1422 Thanks to Brad Fitzpatrick, Anatoly Vorobey, Steven Grimm, and Dustin 1423 Sallings, for their work on the memcached server. 1424 </t> 1425 1426 <t> 1427 Thanks to Sean Chittenden, Jonathan Steinert, Brian Aker, Evan Martin, 1428 Nathan Neulinger, Eric Hodel, Michael Johnson, Paul Querna, Jamie 1429 McCarthy, Philip Neustrom, Andrew O'Brien, Josh Rotenberg, Robin H. 1430 Johnson, Tim Yardley, Paolo Borelli, Eli Bingham, Jean-Francois 1431 Bustarret, Paul G, Paul Lindner, Alan Kasindorf, Chris Goffinet, Tomash 1432 Brechko, and others for their work reporting bugs and maintaining 1433 memcached client libraries and bindings in many languages. 1434 </t> 1435 </section> 1436 </back> 1437 1438</rfc> 1439 1440