1Protocol 2-------- 3 4Clients of memcached communicate with server through TCP connections. 5(A UDP interface is also available; details are below under "UDP 6protocol.") A given running memcached server listens on some 7(configurable) port; clients connect to that port, send commands to 8the server, read responses, and eventually close the connection. 9 10There is no need to send any command to end the session. A client may 11just close the connection at any moment it no longer needs it. Note, 12however, that clients are encouraged to cache their connections rather 13than reopen them every time they need to store or retrieve data. This 14is because memcached is especially designed to work very efficiently 15with a very large number (many hundreds, more than a thousand if 16necessary) of open connections. Caching connections will eliminate the 17overhead associated with establishing a TCP connection (the overhead 18of preparing for a new connection on the server side is insignificant 19compared to this). 20 21There are two kinds of data sent in the memcache protocol: text lines 22and unstructured data. Text lines are used for commands from clients 23and responses from servers. Unstructured data is sent when a client 24wants to store or retrieve data. The server will transmit back 25unstructured data in exactly the same way it received it, as a byte 26stream. The server doesn't care about byte order issues in 27unstructured data and isn't aware of them. There are no limitations on 28characters that may appear in unstructured data; however, the reader 29of such data (either a client or a server) will always know, from a 30preceding text line, the exact length of the data block being 31transmitted. 32 33Text lines are always terminated by \r\n. Unstructured data is _also_ 34terminated by \r\n, even though \r, \n or any other 8-bit characters 35may also appear inside the data. Therefore, when a client retrieves 36data from a server, it must use the length of the data block (which it 37will be provided with) to determine where the data block ends, and not 38the fact that \r\n follows the end of the data block, even though it 39does. 40 41Keys 42---- 43 44Data stored by memcached is identified with the help of a key. A key 45is a text string which should uniquely identify the data for clients 46that are interested in storing and retrieving it. Currently the 47length limit of a key is set at 250 characters (of course, normally 48clients wouldn't need to use such long keys); the key must not include 49control characters or whitespace. 50 51Commands 52-------- 53 54There are three types of commands. 55 56Storage commands (there are six: "set", "add", "replace", "append" 57"prepend" and "cas") ask the server to store some data identified by a 58key. The client sends a command line, and then a data block; after 59that the client expects one line of response, which will indicate 60success or failure. 61 62Retrieval commands ("get", "gets", "gat", and "gats") ask the server to 63retrieve data corresponding to a set of keys (one or more keys in one 64request). The client sends a command line, which includes all the 65requested keys; after that for each item the server finds it sends to 66the client one response line with information about the item, and one 67data block with the item's data; this continues until the server 68finished with the "END" response line. 69 70All other commands don't involve unstructured data. In all of them, 71the client sends one command line, and expects (depending on the 72command) either one line of response, or several lines of response 73ending with "END" on the last line. 74 75A command line always starts with the name of the command, followed by 76parameters (if any) delimited by whitespace. Command names are 77lower-case and are case-sensitive. 78 79Meta Commands 80------------- 81 82Meta commands are a set of new ASCII-based commands. They follow the same 83structure of the original commands but have a new flexible feature set. 84Meta commands incorporate most features available in the binary protocol, as 85well as a flag system to make the commands flexible rather than having a 86large number of high level commands. These commands completely replace the 87usage of basic Storage and Retrieval commands. 88 89Meta flags are not to be confused with client bitflags, which is an opaque 90number passed by the client. Meta flags change how the command operates, but 91they are not stored in cache. 92 93These work mixed with normal protocol commands on the same connection. All 94existing commands continue to work. The meta commands will not replace 95specialized commands that do not sit in the Storage or Retrieval categories 96noted in the 'Commands' section above. 97 98All meta commands follow a basic syntax: 99 100<cm> <key> <datalen*> <flag1> <flag2> <...>\r\n 101 102Where <cm> is a 2 character command code. 103<datalen> is only for commands with payloads, like set. 104 105Responses look like: 106 107<RC> <datalen*> <flag1> <flag2> <...>\r\n 108 109Where <RC> is a 2 character return code. The number of flags returned are 110based off of the flags supplied. 111 112<datalen> is only for responses with payloads, with the return code 'VA'. 113 114Flags are single character codes, ie 'q' or 'k' or 'I', which adjust the 115behavior of the command. If a flag requests a response flag (ie 't' for TTL 116remaining), it is returned in the same order as they were in the original 117command, though this is not strict. 118 119Flags are single character codes, ie 'q' or 'k' or 'O', which adjust the 120behavior of a command. Flags may contain token arguments, which come after the 121flag and before the next space or newline, ie 'Oopaque' or 'Kuserkey'. Flags 122can return new data or reflect information, in the same order they were 123supplied in the request. Sending an 't' flag with a get for an item with 20 124seconds of TTL remaining, would return 't20' in the response. 125 126All commands accept a tokens 'P' and 'L' which are completely ignored. The 127arguments to 'P' and 'L' can be used as hints or path specifications to a 128proxy or router inbetween a client and a memcached daemon. For example, a 129client may prepend a "path" in the key itself: "mg /path/foo v" or in a proxy 130token: "mg foo Lpath/ v" - the proxy may then optionally remove or forward the 131token to a memcached daemon, which will ignore them. 132 133Syntax errors are handled the same as noted under 'Error strings' section 134below. 135 136For usage examples beyond basic syntax, please see the wiki: 137https://github.com/memcached/memcached/wiki/MetaCommands 138 139Expiration times 140---------------- 141 142Some commands involve a client sending some kind of expiration time 143(relative to an item or to an operation requested by the client) to 144the server. In all such cases, the actual value sent may either be 145Unix time (number of seconds since January 1, 1970, as a 32-bit 146value), or a number of seconds starting from current time. In the 147latter case, this number of seconds may not exceed 60*60*24*30 (number 148of seconds in 30 days); if the number sent by a client is larger than 149that, the server will consider it to be real Unix time value rather 150than an offset from current time. 151 152Note that a TTL of 1 will sometimes immediately expire. Time is internally 153updated on second boundaries, which makes expiration time roughly +/- 1s. 154This more proportionally affects very low TTL's. 155 156Error strings 157------------- 158 159Each command sent by a client may be answered with an error string 160from the server. These error strings come in three types: 161 162- "ERROR\r\n" 163 164 means the client sent a nonexistent command name. 165 166- "CLIENT_ERROR <error>\r\n" 167 168 means some sort of client error in the input line, i.e. the input 169 doesn't conform to the protocol in some way. <error> is a 170 human-readable error string. 171 172- "SERVER_ERROR <error>\r\n" 173 174 means some sort of server error prevents the server from carrying 175 out the command. <error> is a human-readable error string. In cases 176 of severe server errors, which make it impossible to continue 177 serving the client (this shouldn't normally happen), the server will 178 close the connection after sending the error line. This is the only 179 case in which the server closes a connection to a client. 180 181 182In the descriptions of individual commands below, these error lines 183are not again specifically mentioned, but clients must allow for their 184possibility. 185 186Authentication 187-------------- 188 189Optional username/password token authentication (see -Y option). Used by 190sending a fake "set" command with any key: 191 192set <key> <flags> <exptime> <bytes>\r\n 193username password\r\n 194 195key, flags, and exptime are ignored for authentication. Bytes is the length 196of the username/password payload. 197 198- "STORED\r\n" indicates success. After this point any command should work 199 normally. 200 201- "CLIENT_ERROR [message]\r\n" will be returned if authentication fails for 202 any reason. 203 204Storage commands 205---------------- 206 207First, the client sends a command line which looks like this: 208 209<command name> <key> <flags> <exptime> <bytes> [noreply]\r\n 210cas <key> <flags> <exptime> <bytes> <cas unique> [noreply]\r\n 211 212- <command name> is "set", "add", "replace", "append" or "prepend" 213 214 "set" means "store this data". 215 216 "add" means "store this data, but only if the server *doesn't* already 217 hold data for this key". 218 219 "replace" means "store this data, but only if the server *does* 220 already hold data for this key". 221 222 "append" means "add this data to an existing key after existing data". 223 224 "prepend" means "add this data to an existing key before existing data". 225 226 The append and prepend commands do not accept flags or exptime. 227 They update existing data portions, and ignore new flag and exptime 228 settings. 229 230 "cas" is a check and set operation which means "store this data but 231 only if no one else has updated since I last fetched it." 232 233- <key> is the key under which the client asks to store the data 234 235- <flags> is an arbitrary 16-bit unsigned integer (written out in 236 decimal) that the server stores along with the data and sends back 237 when the item is retrieved. Clients may use this as a bit field to 238 store data-specific information; this field is opaque to the server. 239 Note that in memcached 1.2.1 and higher, flags may be 32-bits, instead 240 of 16, but you might want to restrict yourself to 16 bits for 241 compatibility with older versions. 242 243- <exptime> is expiration time. If it's 0, the item never expires 244 (although it may be deleted from the cache to make place for other 245 items). If it's non-zero (either Unix time or offset in seconds from 246 current time), it is guaranteed that clients will not be able to 247 retrieve this item after the expiration time arrives (measured by 248 server time). If a negative value is given the item is immediately 249 expired. 250 251- <bytes> is the number of bytes in the data block to follow, *not* 252 including the delimiting \r\n. <bytes> may be zero (in which case 253 it's followed by an empty data block). 254 255- <cas unique> is a unique 64-bit value of an existing entry. 256 Clients should use the value returned from the "gets" command 257 when issuing "cas" updates. 258 259- "noreply" optional parameter instructs the server to not send the 260 reply. NOTE: if the request line is malformed, the server can't 261 parse "noreply" option reliably. In this case it may send the error 262 to the client, and not reading it on the client side will break 263 things. Client should construct only valid requests. 264 265After this line, the client sends the data block: 266 267<data block>\r\n 268 269- <data block> is a chunk of arbitrary 8-bit data of length <bytes> 270 from the previous line. 271 272After sending the command line and the data block the client awaits 273the reply, which may be: 274 275- "STORED\r\n", to indicate success. 276 277- "NOT_STORED\r\n" to indicate the data was not stored, but not 278because of an error. This normally means that the 279condition for an "add" or a "replace" command wasn't met. 280 281- "EXISTS\r\n" to indicate that the item you are trying to store with 282a "cas" command has been modified since you last fetched it. 283 284- "NOT_FOUND\r\n" to indicate that the item you are trying to store 285with a "cas" command did not exist. 286 287 288Retrieval command: 289------------------ 290 291The retrieval commands "get" and "gets" operate like this: 292 293get <key>*\r\n 294gets <key>*\r\n 295 296- <key>* means one or more key strings separated by whitespace. 297 298After this command, the client expects zero or more items, each of 299which is received as a text line followed by a data block. After all 300the items have been transmitted, the server sends the string 301 302"END\r\n" 303 304to indicate the end of response. 305 306Each item sent by the server looks like this: 307 308VALUE <key> <flags> <bytes> [<cas unique>]\r\n 309<data block>\r\n 310 311- <key> is the key for the item being sent 312 313- <flags> is the flags value set by the storage command 314 315- <bytes> is the length of the data block to follow, *not* including 316 its delimiting \r\n 317 318- <cas unique> is a unique 64-bit integer that uniquely identifies 319 this specific item. 320 321- <data block> is the data for this item. 322 323If some of the keys appearing in a retrieval request are not sent back 324by the server in the item list this means that the server does not 325hold items with such keys (because they were never stored, or stored 326but deleted to make space for more items, or expired, or explicitly 327deleted by a client). 328 329 330Deletion 331-------- 332 333The command "delete" allows for explicit deletion of items: 334 335delete <key> [noreply]\r\n 336 337- <key> is the key of the item the client wishes the server to delete 338 339- "noreply" optional parameter instructs the server to not send the 340 reply. See the note in Storage commands regarding malformed 341 requests. 342 343The response line to this command can be one of: 344 345- "DELETED\r\n" to indicate success 346 347- "NOT_FOUND\r\n" to indicate that the item with this key was not 348 found. 349 350See the "flush_all" command below for immediate invalidation 351of all existing items. 352 353 354Increment/Decrement 355------------------- 356 357Commands "incr" and "decr" are used to change data for some item 358in-place, incrementing or decrementing it. The data for the item is 359treated as decimal representation of a 64-bit unsigned integer. If 360the current data value does not conform to such a representation, the 361incr/decr commands return an error (memcached <= 1.2.6 treated the 362bogus value as if it were 0, leading to confusion). Also, the item 363must already exist for incr/decr to work; these commands won't pretend 364that a non-existent key exists with value 0; instead, they will fail. 365 366The client sends the command line: 367 368incr <key> <value> [noreply]\r\n 369 370or 371 372decr <key> <value> [noreply]\r\n 373 374- <key> is the key of the item the client wishes to change 375 376- <value> is the amount by which the client wants to increase/decrease 377the item. It is a decimal representation of a 64-bit unsigned integer. 378 379- "noreply" optional parameter instructs the server to not send the 380 reply. See the note in Storage commands regarding malformed 381 requests. 382 383The response will be one of: 384 385- "NOT_FOUND\r\n" to indicate the item with this value was not found 386 387- <value>\r\n , where <value> is the new value of the item's data, 388 after the increment/decrement operation was carried out. 389 390Note that underflow in the "decr" command is caught: if a client tries 391to decrease the value below 0, the new value will be 0. Overflow in 392the "incr" command will wrap around the 64 bit mark. 393 394Note also that decrementing a number such that it loses length isn't 395guaranteed to decrement its returned length. The number MAY be 396space-padded at the end, but this is purely an implementation 397optimization, so you also shouldn't rely on that. 398 399Touch 400----- 401 402The "touch" command is used to update the expiration time of an existing item 403without fetching it. 404 405touch <key> <exptime> [noreply]\r\n 406 407- <key> is the key of the item the client wishes the server to touch 408 409- <exptime> is expiration time. Works the same as with the update commands 410 (set/add/etc). This replaces the existing expiration time. If an existing 411 item were to expire in 10 seconds, but then was touched with an 412 expiration time of "20", the item would then expire in 20 seconds. 413 414- "noreply" optional parameter instructs the server to not send the 415 reply. See the note in Storage commands regarding malformed 416 requests. 417 418The response line to this command can be one of: 419 420- "TOUCHED\r\n" to indicate success 421 422- "NOT_FOUND\r\n" to indicate that the item with this key was not 423 found. 424 425Get And Touch 426------------- 427 428The "gat" and "gats" commands are used to fetch items and update the 429expiration time of an existing items. 430 431gat <exptime> <key>*\r\n 432gats <exptime> <key>*\r\n 433 434- <exptime> is expiration time. 435 436- <key>* means one or more key strings separated by whitespace. 437 438After this command, the client expects zero or more items, each of 439which is received as a text line followed by a data block. After all 440the items have been transmitted, the server sends the string 441 442"END\r\n" 443 444to indicate the end of response. 445 446Each item sent by the server looks like this: 447 448VALUE <key> <flags> <bytes> [<cas unique>]\r\n 449<data block>\r\n 450 451- <key> is the key for the item being sent 452 453- <flags> is the flags value set by the storage command 454 455- <bytes> is the length of the data block to follow, *not* including 456 its delimiting \r\n 457 458- <cas unique> is a unique 64-bit integer that uniquely identifies 459 this specific item. 460 461- <data block> is the data for this item. 462 463Meta Debug 464---------- 465 466The meta debug command is a human readable dump of all available internal 467metadata of an item, minus the value. 468 469me <key> <flag>\r\n 470 471- <key> means one key string. 472- if <flag> is 'b', then <key> is a base64 encoded binary value. the response 473 key will also be base64 encoded. 474 475The response looks like: 476 477ME <key> <k>=<v>*\r\n 478 479A miss looks like: 480 481EN\r\n 482 483Each of the keys and values are the internal data for the item. 484 485exp = expiration time 486la = time in seconds since last access 487cas = CAS ID 488fetch = whether an item has been fetched before 489cls = slab class id 490size = total size in bytes 491 492Others may be added. 493 494Meta Get 495-------- 496 497The meta get command is the generic command for retrieving key data from 498memcached. Based on the flags supplied, it can replace all of the commands: 499"get", "gets", "gat", "gats", "touch", as well as adding new options. 500 501mg <key> <flags>*\r\n 502 503- <key> means one key string. Unlike "get" metaget can only take a single key. 504 505- <flags> are a set of single character codes ended with a space or newline. 506 flags may have token strings after the initial character. 507 508After this command, the client expects an item to be returned, received as a 509text line followed by an optional data block. 510 511If a response line appearing in a retrieval request is not sent back 512by the server this means that the server does not 513have the item (because it was never stored, or stored 514but deleted to make space for more items, or expired, or explicitly 515deleted by a client). 516 517An item sent by the server looks like: 518 519VA <size> <flags>*\r\n 520<data block>\r\n 521 522- <size> is the size of <data block> in bytes, minus the \r\n 523 524- <flags>* are flags returned by the server, based on the command flags. 525 They are added in order specified by the flags sent. 526 527- <data block> is the data for this item. Note that the data block is 528 optional, requiring the 'v' flag to be supplied. 529 530If the request did not ask for a value in the response (v) flag, the server 531response looks like: 532 533HD <flags>*\r\n 534 535If the request resulted in a miss, the response looks like: 536 537EN\r\n 538 539Unless the (q) flag was supplied, which suppresses the status code for a miss. 540 541The flags used by the 'mg' command are: 542 543- b: interpret key as base64 encoded binary value 544- c: return item cas token 545- f: return client flags token 546- h: return whether item has been hit before as a 0 or 1 547- k: return key as a token 548- l: return time since item was last accessed in seconds 549- O(token): opaque value, consumes a token and copies back with response 550- q: use noreply semantics for return codes. 551- s: return item size token 552- t: return item TTL remaining in seconds (-1 for unlimited) 553- u: don't bump the item in the LRU 554- v: return item value in <data block> 555 556These flags can modify the item: 557- E(token): use token as new CAS value if item is modified 558- N(token): vivify on miss, takes TTL as a argument 559- R(token): if remaining TTL is less than token, win for recache 560- T(token): update remaining TTL 561 562These extra flags can be added to the response: 563- W: client has "won" the recache flag 564- X: item is stale 565- Z: item has already sent a winning flag 566 567The flags are now repeated with detailed information where useful: 568 569- b: interpret key as base64 encoded binary value 570 571This flag instructs memcached to run a base64 decoder on <key> before looking 572it up. This allows storing and fetching of binary packed keys, so long as they 573are sent to memcached in base64 encoding. 574 575If 'b' flag is sent in the response, and a key is returned via 'k', this 576signals to the client that the key is base64 encoded binary. 577 578- h: return whether item has been hit before as a 0 or 1 579- l: return time since item was last accessed in seconds 580 581The above two flags return the value of "hit before?" and "last access time" 582before the command was processed. Otherwise this would always show a 1 for 583hit or always show an access time of "0" unless combined with the "u" flag. 584 585- O(token): opaque value, consumes a token and copies back with response 586 587The O(opaque) token is used by this and other commands to allow easier 588pipelining of requests while saving bytes on the wire for responses. For 589example: if pipelining three get commands together, you may not know which 590response belongs to which without also retrieving the key. If the key is very 591long this can generate a lot of traffic, especially if the data block is very 592small. Instead, you can supply an "O" flag for each mg with tokens of "1" "2" 593and "3", to match up responses to the request. 594 595Opaque tokens may be up to 32 bytes in length, and are a string similar to 596keys. 597 598- q: use noreply semantics for return codes. 599 600Noreply is a method of reducing the amount of data sent back by memcached to 601the client for normal responses. In the case of metaget, if an item is not 602available the "VA" line is normally not sent, and the response is terminated by 603"EN\r\n". 604 605With noreply enabled, the "EN\r\n" marker is suppressed. This allows you to 606pipeline several mg's together and read all of the responses without the 607"EN\r\n" lines in the middle. 608 609Errors are always returned. 610 611- u: don't bump the item in the LRU 612 613It is possible to access an item without causing it to be "bumped" to the head 614of the LRU. This also avoids marking an item as being hit or updating its last 615access time. 616 617- v: return item value in <data block> 618 619The data block for a metaget response is optional, requiring this flag to be 620passed in. The response code also changes from "HD" to "VA <size>" 621 622These flags can modify the item: 623- E(token): use token as new CAS value if item is modified 624 625Normally when an item is created it is given a CAS value from an internal 626atomically incrementing counter. This allows overriding the CAS (8 byte 627unsigned integer) with the specified value. This is useful for using an 628external system to version cache data (row versions, clocks, etc). 629 630- N(token): vivify on miss, takes TTL as a argument 631 632Used to help with so called "dog piling" problems with recaching of popular 633items. If supplied, and metaget does not find the item in cache, it will 634create a stub item with the key and TTL as supplied. If such an item is 635created a 'W' flag is added to the response to indicate to a client that they 636have "won" the right to recache an item. 637 638The automatically created item has 0 bytes of data. 639 640Further requests will see a 'Z' flag to indicate that another client has 641already received the win flag. 642 643Can be combined with CAS flags to gate the update further. 644 645- R(token): if token is less than remaining TTL win for recache 646 647Similar to and can be combined with 'N'. If the remaining TTL of an item is 648below the supplied token, return a 'W' flag to indicate the client has "won" 649the right to recache an item. This allows refreshing an item before it leads to 650a miss. 651 652- T(token): update remaining TTL 653 654Similar to "touch" and "gat" commands, updates the remaining TTL of an item if 655hit. 656 657These extra flags can be added to the response: 658- W: client has "won" the recache flag 659 660When combined with N or R flags, a client may be informed they have "won" 661ownership of a cache item. This allows a single client to be atomically 662notified that it should cache or update an item. Further clients requesting 663the item can use the existing data block (if valid or stale), retry, wait, or 664take some other action while the item is missing. 665 666This is used when the act of recaching an item can cause undue load on another 667system (CPU, database accesses, time, and so on). 668 669- X: item is stale 670 671Items can be marked as stale by the metadelete command. This indicates to the 672client that an object needs to be updated, and that it should make a decision 673o if potentially stale data is safe to use. 674 675This is used when you want to convince clients to recache an item, but it's 676safe to use pre-existing data while the recache happens. 677 678- Z: item has already sent a winning flag 679 680When combined with the X flag, or the client N or R flags, this extra response 681flag indicates to a client that a different client is responsible for 682recaching this item. If there is data supplied it may use it, or the client 683may decide to retry later or take some other action. 684 685Meta Set 686-------- 687 688The meta set command a generic command for storing data to memcached. Based 689on the flags supplied, it can replace all storage commands (see token M) as 690well as adds new options. 691 692ms <key> <datalen> <flags>*\r\n 693 694- <key> means one key string. 695 696- <datalen> is the length of the payload data. 697 698- <flags> are a set of single character codes ended with a space or newline. 699 flags may have strings after the initial character. 700 701After this line, the client sends the data block: 702 703<data block>\r\n 704 705- <data block> is a chunk of arbitrary 8-bit data of length supplied by an 'S' 706 flag and token from the request line. If no 'S' flag is supplied the data 707 is assumed to be 0 length. 708 709After sending the command line and the data block the client awaits 710the reply, which is of the format: 711 712<CD> <flags>*\r\n 713 714Where CD is one of: 715 716- "HD" (STORED), to indicate success. 717 718- "NS" (NOT_STORED), to indicate the data was not stored, but not 719because of an error. 720 721- "EX" (EXISTS), to indicate that the item you are trying to store with 722CAS semantics has been modified since you last fetched it. 723 724- "NF" (NOT_FOUND), to indicate that the item you are trying to store 725with CAS semantics did not exist. 726 727The flags used by the 'ms' command are: 728 729- b: interpret key as base64 encoded binary value (see metaget) 730- c: return CAS value if successfully stored. 731- C(token): compare CAS value when storing item 732- E(token): use token as new CAS value (see metaget for detail) 733- F(token): set client flags to token (32 bit unsigned numeric) 734- I: invalidate. set-to-invalid if supplied CAS is older than item's CAS 735- k: return key as a token 736- O(token): opaque value, consumes a token and copies back with response 737- q: use noreply semantics for return codes 738- s: return the size of the stored item on success (ie; new size on append) 739- T(token): Time-To-Live for item, see "Expiration" above. 740- M(token): mode switch to change behavior to add, replace, append, prepend 741- N(token): if in append mode, autovivify on miss with supplied TTL 742 743The flags are now repeated with detailed information where useful: 744 745- c: returns the CAS value on successful storage. Will return 0 on error, but 746 clients must not depend on the return value being zero. In future versions 747this may return the current CAS value for "EX" return code conditions. 748 749- C(token): compare CAS value when storing item 750 751Similar to the basic "cas" command, only store item if the supplied token 752matches the current CAS value of the item. When combined with the 'I' flag, a 753CAS value that is _lower_ than the current value may be accepted, but the item 754will be marked as "stale", returning the X flag with mget requests. 755 756- F(token): set client flags to token (32 bit unsigned numeric) 757 758Sets flags to 0 if not supplied. 759 760- I: invalid. set-to-invalid if CAS is older than it should be. 761 762Functional when combined with 'C' flag above. 763 764- O(token): opaque value, consumes a token and copies back with response 765 766See description under 'Meta Get' 767 768- q: use noreply semantics for return codes 769 770Noreply is a method of reducing the amount of data sent back by memcached to 771the client for normal responses. In the case of metaset, a response that 772would start with "HD" will not be sent. Any other code, such as "EX" 773(EXISTS) will still be returned. 774 775Errors are always returned. 776 777- M(token): mode switch. Takes a single character for the mode. 778 779E: "add" command. LRU bump and return NS if item exists. Else 780add. 781A: "append" command. If item exists, append the new value to its data. 782P: "prepend" command. If item exists, prepend the new value to its data. 783R: "replace" command. Set only if item already exists. 784S: "set" command. The default mode, added for completeness. 785 786The "cas" command is supplanted by specifying the cas value with the 'C' flag. 787Append and Prepend modes will also respect a supplied cas value. 788 789- N(token): if in append mode, autovivify on miss with supplied TTL 790 791Append and Prepend modes normally ignore the T argument, as they cannot create 792a new item on a miss. If N is supplied, and append reaches a miss, it will 793create a new item seeded with the data from the append command. It uses the 794TTL from N instead of T to be consistent with the usage of N in other 795commands. 796 797Meta Delete 798----------- 799 800The meta delete command allows for explicit deletion of items, as well as 801marking items as "stale" to allow serving items as stale during revalidation. 802 803md <key> <flags>*\r\n 804 805- <key> means one key string. 806 807- <flags> are a set of single character codes ended with a space or newline. 808 flags may have strings after the initial character. 809 810The response is in the format: 811 812<CD> <flags> <tokens>*\r\n 813 814Where CD is one of: 815 816- "HD" (DELETED), to indicate success 817 818- "NF" (NOT_FOUND), to indicate that the item with this key was not found. 819 820- "EX" (EXISTS), to indicate that the supplied CAS token does not match the 821 stored item. 822 823The flags used by the 'md' command are: 824 825- b: interpret key as base64 encoded binary value (see metaget) 826- C(token): compare CAS value 827- E(token): use token as new CAS value (see metaget for detail) 828- I: invalidate. mark as stale, bumps CAS. 829- k: return key 830- O(token): opaque to copy back. 831- q: noreply 832- T(token): updates TTL, only when paired with the 'I' flag 833- x: removes the item value, but leaves the item. 834 835The flags are now repeated with detailed information where useful: 836 837- C(token): compare CAS value 838 839Can be used to only delete or mark-stale if a supplied CAS value matches. 840 841- I: invalidate. mark as stale, bumps CAS. 842 843Instead of removing an item, this will give the item a new CAS value and mark 844it as stale. This means when it is later fetched by metaget, the client will 845be supplied an 'X' flag to show the data is stale and needs to be recached. 846 847- O(token): opaque to copy back. 848 849See description under 'Meta Get' 850 851- q: noreply 852 853See description under 'Meta Set'. In the case of meta delete, this will hide 854response lines with the code "DE". It will still return any other responses. 855 856- T(token): updates TTL, only when paired with the 'I' flag 857 858When marking an item as stale with 'I', the 'T' flag can be used to update the 859TTL as well; limiting the amount of time an item will live while stale and 860waiting to be recached. 861 862- x: removes the item value, but leaves the item. 863 864This deletes the value off of an item (by replacing it with an empty value 865item atomically). Combined with I this can leave what is effectively a 866tombstone of a previous value. 867 868Meta Arithmetic 869--------------- 870 871The meta arithmetic command allows for basic operations against numerical 872values. This replaces the "incr" and "decr" commands. Values are unsigned 87364bit integers. Decrementing will reach 0 rather than underflow. Incrementing 874can overflow. 875 876ma <key> <flags>*\r\n 877 878- <key> means one key string. 879 880- <flags> are a set of single character codes ended with a space or newline. 881 flags may have strings after the initial character. 882 883The response is in the format: 884 885<CD> <flags> <tokens>*\r\n 886 887Where CD is one of: 888 889- "HD" to indicate success 890 891- "NF" (NOT_FOUND), to indicate that the item with this key was not found. 892 893- "NS" (NOT_STORED), to indicate that the item was not created as requested 894 after a miss. 895 896- "EX" (EXISTS), to indicate that the supplied CAS token does not match the 897 stored item. 898 899If the 'v' flag is supplied, the response is formatted as: 900 901VA <size> <flags>*\r\n 902<number>\r\n 903 904The flags used by the 'ma' command are: 905 906- b: interpret key as base64 encoded binary value (see metaget) 907- C(token): compare CAS value (see mset) 908- E(token): use token as new CAS value (see metaget for detail) 909- N(token): auto create item on miss with supplied TTL 910- J(token): initial value to use if auto created after miss (default 0) 911- D(token): delta to apply (decimal unsigned 64-bit number, default 1) 912- T(token): update TTL on success 913- M(token): mode switch to change between incr and decr modes. 914- O(token): opaque value, consumes a token and copies back with response 915- q: use noreply semantics for return codes (see details under mset) 916- t: return current TTL 917- c: return current CAS value if successful. 918- v: return new value 919- k: return key as a token 920 921The flags are now repeated with detailed information where useful: 922 923- C(token): compare CAS value 924 925Can be used to only incr/decr if a supplied CAS value matches. A new CAS value 926is generated after a delta is applied. Add the 'c' flag to get the new CAS 927value after success. 928 929- N(token): auto create item on miss with supplied TTL 930 931Similar to mget, on a miss automatically create the item. A value can be 932seeded using the J flag. 933 934- J(token): initial value 935 936An unsigned 64-bit integer which will be seeded as the value on a miss. Must be 937combined with an N flag. 938 939- D(token): delta to apply 940 941An unsigned integer to either add or subtract from the currently stored 942number. 943 944- T(token): update TTL 945 946On success, sets the remaining TTL to the supplied value. 947 948-M(token): mode switch. Takes a single character for the mode. 949 950I: Increment mode (default) 951+: Alias for increment 952D: Decrement mode 953-: Alias for decrement 954 955Meta No-Op 956---------- 957 958The meta no-op command exists solely to return a static response code. It 959takes no flags, no arguments. 960 961"mn\r\n" 962 963This returns the static response: 964 965"MN\r\n" 966 967This command is useful when used with the 'q' flag and pipelining commands. 968For example, with 'mg' the response lines are blank on miss when the 'q' flag 969is supplied. If pipelining several 'mg's together with noreply semantics, an 970"mn\r\n" command can be tagged to the end of the chain, which will return an 971"MN\r\n", signalling to a client that all previous commands have been 972processed. 973 974Slabs Reassign 975-------------- 976 977NOTE: This command is subject to change as of this writing. 978 979The slabs reassign command is used to redistribute memory once a running 980instance has hit its limit. It might be desirable to have memory laid out 981differently than was automatically assigned after the server started. 982 983slabs reassign <source class> <dest class>\r\n 984 985- <source class> is an id number for the slab class to steal a page from 986 987A source class id of -1 means "pick from any valid class" 988 989- <dest class> is an id number for the slab class to move a page to 990 991The response line could be one of: 992 993- "OK" to indicate the page has been scheduled to move 994 995- "BUSY [message]" to indicate a page is already being processed, try again 996 later. 997 998- "BADCLASS [message]" a bad class id was specified 999 1000- "NOSPARE [message]" source class has no spare pages 1001 1002- "NOTFULL [message]" dest class must be full to move new pages to it 1003 1004- "UNSAFE [message]" source class cannot move a page right now 1005 1006- "SAME [message]" must specify different source/dest ids. 1007 1008Slabs Automove 1009-------------- 1010 1011NOTE: This command is subject to change as of this writing. 1012 1013The slabs automove command enables a background thread which decides on its 1014own when to move memory between slab classes. Its implementation and options 1015will likely be in flux for several versions. See the wiki/mailing list for 1016more details. 1017 1018The automover can be enabled or disabled at runtime with this command. 1019 1020slabs automove <0|1|2> 1021 1022- 0|1|2 is the indicator on whether to enable the slabs automover or not. 1023 1024The response should always be "OK\r\n" 1025 1026- <0> means to set the thread on standby 1027 1028- <1> means to return pages to a global pool when there are more than 2 pages 1029 worth of free chunks in a slab class. Pages are then re-assigned back into 1030 other classes as-needed. 1031 1032- <2> is a highly aggressive mode which causes pages to be moved every time 1033 there is an eviction. It is not recommended to run for very long in this 1034 mode unless your access patterns are very well understood. 1035 1036LRU Tuning 1037---------- 1038 1039Memcached supports multiple LRU algorithms, with a few tunables. Effort is 1040made to have sane defaults however you are able to tune while the daemon is 1041running. 1042 1043The traditional model is "flat" mode, which is a single LRU chain per slab 1044class. The newer (with `-o modern` or `-o lru_maintainer`) is segmented into 1045HOT, WARM, COLD. There is also a TEMP LRU. See doc/new_lru.txt for details. 1046 1047lru <tune|mode|temp_ttl> <option list> 1048 1049- "tune" takes numeric arguments "percent hot", "percent warm", 1050 "max hot factor", "max warm age factor". IE: "lru tune 10 25 0.1 2.0". 1051 This would cap HOT_LRU at 10% of the cache, or tail is idle longer than 1052 10% of COLD_LRU. WARM_LRU is up to 25% of cache, or tail is idle longer 1053 than 2x COLD_LRU. 1054 1055- "mode" <flat|segmented>: "flat" is traditional mode. "segmented" uses 1056 HOT|WARM|COLD split. "segmented" mode requires `-o lru_maintainer` at start 1057 time. If switching from segmented to flat mode, the background thread will 1058 pull items from HOT|WARM into COLD queue. 1059 1060- "temp_ttl" <ttl>: If TTL is less than zero, disable usage of TEMP_LRU. If 1061 zero or above, items set with a TTL lower than this will go into TEMP_LRU 1062 and be unevictable until they naturally expire or are otherwise deleted or 1063 replaced. 1064 1065The response line could be one of: 1066 1067- "OK" to indicate a successful update of the settings. 1068 1069- "ERROR [message]" to indicate a failure or improper arguments. 1070 1071LRU_Crawler 1072----------- 1073 1074NOTE: This command (and related commands) are subject to change as of this 1075writing. 1076 1077The LRU Crawler is an optional background thread which will walk from the tail 1078toward the head of requested slab classes, actively freeing memory for expired 1079items. This is useful if you have a mix of items with both long and short 1080TTL's, but aren't accessed very often. This system is not required for normal 1081usage, and can add small amounts of latency and increase CPU usage. 1082 1083lru_crawler <enable|disable> 1084 1085- Enable or disable the LRU Crawler background thread. 1086 1087The response line could be one of: 1088 1089- "OK" to indicate the crawler has been started or stopped. 1090 1091- "ERROR [message]" something went wrong while enabling or disabling. 1092 1093lru_crawler sleep <microseconds> 1094 1095- The number of microseconds to sleep in between each item checked for 1096 expiration. Smaller numbers will obviously impact the system more. 1097 A value of "0" disables the sleep, "1000000" (one second) is the max. 1098 1099The response line could be one of: 1100 1101- "OK" 1102 1103- "CLIENT_ERROR [message]" indicating a format or bounds issue. 1104 1105lru_crawler tocrawl <32u> 1106 1107- The maximum number of items to inspect in a slab class per run request. This 1108 allows you to avoid scanning all of very large slabs when it is unlikely to 1109 find items to expire. 1110 1111The response line could be one of: 1112 1113- "OK" 1114 1115- "CLIENT_ERROR [message]" indicating a format or bound issue. 1116 1117lru_crawler crawl <classid,classid,classid|all> 1118 1119- Takes a single, or a list of, numeric classids (ie: 1,3,10). This instructs 1120 the crawler to start at the tail of each of these classids and run to the 1121 head. The crawler cannot be stopped or restarted until it completes the 1122 previous request. 1123 1124 The special keyword "all" instructs it to crawl all slabs with items in 1125 them. 1126 1127The response line could be one of: 1128 1129- "OK" to indicate successful launch. 1130 1131- "BUSY [message]" to indicate the crawler is already processing a request. 1132 1133- "BADCLASS [message]" to indicate an invalid class was specified. 1134 1135lru_crawler metadump <classid,classid,classid|all|hash> 1136 1137- Similar in function to the above "lru_crawler crawl" command, this function 1138 outputs one line for every valid item found in the matching slab classes. 1139 Similar to "cachedump", but does not lock the cache and can return all 1140 items, not just 1MB worth. 1141 1142 if "hash" is specified instead of a classid or "all", the crawler will dump 1143 items by directly walking the hash table instead of the LRU's. This makes it 1144 more likely all items will be visited once as LRU reordering and locking can 1145 cause frequently accessed items to be missed. 1146 1147 Lines are in "key=value key2=value2" format, with value being URI encoded 1148 (ie: %20 for a space). 1149 1150 The exact keys available are subject to change, but will include at least: 1151 1152 "key", "exp" (expiration time), "la", (last access time), "cas", 1153 "fetch" (if item has been fetched before). 1154 1155The response line could be one of: 1156 1157- "OK" to indicate successful launch. 1158 1159- "BUSY [message]" to indicate the crawler is already processing a request. 1160 1161- "BADCLASS [message]" to indicate an invalid class was specified. 1162 1163lru_crawler mgdump <classid,classid,classid|all|hash> 1164 1165- Similar in function to the above "lru_crawler crawl" command, this function 1166 outputs one line for every valid item found in the matching slab classes. 1167 1168 If "hash" is specified instead of a classid or "all", the crawler will dump 1169 items by directly walking the hash table instead of the LRU's. This makes it 1170 more likely all items will be visited once as LRU reordering and locking can 1171 cause frequently accessed items to be missed. 1172 1173 Lines are in a basic metaget format, like: "mg key\r\n". If a key is in 1174 binary format: "mg base64encodedkey b\r\n" 1175 A user may then take each line, append any flags they want, and run those 1176 commands against the server to fetch exactly what they want to know. 1177 1178The response line could be one of: 1179 1180- "OK" to indicate successful launch. 1181 1182- "BUSY [message]" to indicate the crawler is already processing a request. 1183 1184- "BADCLASS [message]" to indicate an invalid class was specified. 1185 1186 1187 1188Watchers 1189-------- 1190 1191Watchers are a way to connect to memcached and inspect what's going on 1192internally. This is an evolving feature so new endpoints should show up over 1193time. 1194 1195watch <arg1> <arg2> <arg3> 1196 1197possible arguments: 1198fetchers 1199mutations 1200evictions 1201connevents 1202proxyreqs 1203proxyevents 1204proxyuser 1205deletions 1206 1207- Turn connection into a watcher. Options can be stacked and are 1208 space-separated. Logs will be sent to the watcher until it disconnects. 1209 1210The response line could be one of: 1211 1212- "OK" to indicate the watcher is ready to send logs. 1213 1214- "ERROR [message]" something went wrong while enabling. 1215 1216The response format is in "key=value key2=value2" format, for easy parsing. 1217Lines are prepending with "ts=" for a timestamp and "gid=" for a global ID 1218number of the log line. Given how logs are collected internally they may be 1219printed out of order. If this is important the GID may be used to put log 1220lines back in order. 1221 1222The value of keys (and potentially other things) are "URI encoded". Since most 1223keys used conform to standard ASCII, this should have no effect. For keys with 1224less standard or binary characters, "%NN"'s are inserted to represent the 1225byte, ie: "n%2Cfoo" for "n,foo". 1226 1227The arguments are: 1228 1229- "fetchers": Currently emits logs every time an item is fetched internally. 1230 This means a "set" command would also emit an item_get log, as it checks for 1231 an item before replacing it. Multigets should also emit multiple lines. 1232 1233- "mutations": Currently emits logs when an item is stored in most cases. 1234 Shows errors for most cases when items cannot be stored. 1235 1236- "evictions": Shows some information about items as they are evicted from the 1237 cache. Useful in seeing if items being evicted were actually used, and which 1238 keys are getting removed. 1239 1240- "connevents": Emits logs when connections are opened and closed, i.e. when 1241 clients connect or disconnect. For TCP transports, logs indicate the remote 1242 address IP and port. Connection close events additionally supply a reason for 1243 closing the connection. If TLS is enabled, this stream also contains 1244 detailed TLS protocol errors. 1245 1246- "proxyreqs": Emits detailed timing logs about requests/responses being 1247 returned to a client while in proxy mode. The conditions which logs are 1248 written here may be influenced by configuration. 1249 1250- "proxyevents": Emits internal proxy errors and system events, such as 1251 configuration reloads. 1252 1253- "proxyuser": Emits log entries created from lua configuration files. 1254 1255- "deletions": Emits logs when an item is successfully deleted from the 1256 cache using `delete` or `md` commands. delete misses wouldn't be logged 1257 1258Statistics 1259---------- 1260 1261The command "stats" is used to query the server about statistics it 1262maintains and other internal data. It has two forms. Without 1263arguments: 1264 1265stats\r\n 1266 1267it causes the server to output general-purpose statistics and 1268settings, documented below. In the other form it has some arguments: 1269 1270stats <args>\r\n 1271 1272Depending on <args>, various internal data is sent by the server. The 1273kinds of arguments and the data sent are not documented in this version 1274of the protocol, and are subject to change for the convenience of 1275memcache developers. 1276 1277 1278General-purpose statistics 1279-------------------------- 1280 1281Upon receiving the "stats" command without arguments, the server sends 1282a number of lines which look like this: 1283 1284STAT <name> <value>\r\n 1285 1286The server terminates this list with the line 1287 1288END\r\n 1289 1290In each line of statistics, <name> is the name of this statistic, and 1291<value> is the data. The following is the list of all names sent in 1292response to the "stats" command, together with the type of the value 1293sent for this name, and the meaning of the value. 1294 1295In the type column below, "32u" means a 32-bit unsigned integer, "64u" 1296means a 64-bit unsigned integer. '32u.32u' means two 32-bit unsigned 1297integers separated by a colon (treat this as a floating point number). 1298 1299|-----------------------+---------+-------------------------------------------| 1300| Name | Type | Meaning | 1301|-----------------------+---------+-------------------------------------------| 1302| pid | 32u | Process id of this server process | 1303| uptime | 32u | Number of secs since the server started | 1304| time | 32u | current UNIX time according to the server | 1305| version | string | Version string of this server | 1306| pointer_size | 32 | Default size of pointers on the host OS | 1307| | | (generally 32 or 64) | 1308| rusage_user | 32u.32u | Accumulated user time for this process | 1309| | | (seconds:microseconds) | 1310| rusage_system | 32u.32u | Accumulated system time for this process | 1311| | | (seconds:microseconds) | 1312| curr_items | 64u | Current number of items stored | 1313| total_items | 64u | Total number of items stored since | 1314| | | the server started | 1315| bytes | 64u | Current number of bytes used | 1316| | | to store items | 1317| max_connections | 32u | Max number of simultaneous connections | 1318| curr_connections | 32u | Number of open connections | 1319| total_connections | 32u | Total number of connections opened since | 1320| | | the server started running | 1321| rejected_connections | 64u | Conns rejected in maxconns_fast mode | 1322| connection_structures | 32u | Number of connection structures allocated | 1323| | | by the server | 1324| response_obj_oom | 64u | Connections closed by lack of memory | 1325| response_obj_count | 64u | Total response objects in use | 1326| response_obj_bytes | 64u | Total bytes used for resp. objects. is a | 1327| | | subset of bytes from read_buf_bytes. | 1328| read_buf_count | 64u | Total read/resp buffers allocated | 1329| read_buf_bytes | 64u | Total read/resp buffer bytes allocated | 1330| read_buf_bytes_free | 64u | Total read/resp buffer bytes cached | 1331| read_buf_oom | 64u | Connections closed by lack of memory | 1332| reserved_fds | 32u | Number of misc fds used internally | 1333| proxy_conn_requests | 64u | Number of requests received by the proxy | 1334| proxy_conn_errors | 64u | Number of internal errors from proxy | 1335| proxy_conn_oom | 64u | Number of out of memory errors while | 1336| | | serving proxy requests | 1337| proxy_req_active | 64u | Number of in-flight proxy requests | 1338| proxy_req_await | 64u | Number of in-flight proxy async requests | 1339| cmd_get | 64u | Cumulative number of retrieval reqs | 1340| cmd_set | 64u | Cumulative number of storage reqs | 1341| cmd_flush | 64u | Cumulative number of flush reqs | 1342| cmd_touch | 64u | Cumulative number of touch reqs | 1343| get_hits | 64u | Number of keys that have been requested | 1344| | | and found present | 1345| get_misses | 64u | Number of items that have been requested | 1346| | | and not found | 1347| get_expired | 64u | Number of items that have been requested | 1348| | | but had already expired. | 1349| get_flushed | 64u | Number of items that have been requested | 1350| | | but have been flushed via flush_all | 1351| delete_misses | 64u | Number of deletions reqs for missing keys | 1352| delete_hits | 64u | Number of deletion reqs resulting in | 1353| | | an item being removed. | 1354| incr_misses | 64u | Number of incr reqs against missing keys. | 1355| incr_hits | 64u | Number of successful incr reqs. | 1356| decr_misses | 64u | Number of decr reqs against missing keys. | 1357| decr_hits | 64u | Number of successful decr reqs. | 1358| cas_misses | 64u | Number of CAS reqs against missing keys. | 1359| cas_hits | 64u | Number of successful CAS reqs. | 1360| cas_badval | 64u | Number of CAS reqs for which a key was | 1361| | | found, but the CAS value did not match. | 1362| touch_hits | 64u | Number of keys that have been touched | 1363| | | with a new expiration time | 1364| touch_misses | 64u | Number of items that have been touched | 1365| | | and not found | 1366| store_too_large | 64u | Number of rejected storage requests | 1367| | | caused by attempting to write a value | 1368| | | larger than the -I limit | 1369| store_no_memory | 64u | Number of rejected storage requests | 1370| | | caused by exhaustion of the -m memory | 1371| | | limit (relevant when -M is used) | 1372| auth_cmds | 64u | Number of authentication commands | 1373| | | handled, success or failure. | 1374| auth_errors | 64u | Number of failed authentications. | 1375| idle_kicks | 64u | Number of connections closed due to | 1376| | | reaching their idle timeout. | 1377| evictions | 64u | Number of valid items removed from cache | 1378| | | to free memory for new items | 1379| reclaimed | 64u | Number of times an entry was stored using | 1380| | | memory from an expired entry | 1381| bytes_read | 64u | Total number of bytes read by this server | 1382| | | from network | 1383| bytes_written | 64u | Total number of bytes sent by this server | 1384| | | to network | 1385| limit_maxbytes | size_t | Number of bytes this server is allowed to | 1386| | | use for storage. | 1387| accepting_conns | bool | Whether or not server is accepting conns | 1388| listen_disabled_num | 64u | Number of times server has stopped | 1389| | | accepting new connections (maxconns). | 1390| time_in_listen_disabled_us | 1391| | 64u | Number of microseconds in maxconns. | 1392| threads | 32u | Number of worker threads requested. | 1393| | | (see doc/threads.txt) | 1394| conn_yields | 64u | Number of times any connection yielded to | 1395| | | another due to hitting the -R limit. | 1396| hash_power_level | 32u | Current size multiplier for hash table | 1397| hash_bytes | 64u | Bytes currently used by hash tables | 1398| hash_is_expanding | bool | Indicates if the hash table is being | 1399| | | grown to a new size | 1400| expired_unfetched | 64u | Items pulled from LRU that were never | 1401| | | touched by get/incr/append/etc before | 1402| | | expiring | 1403| evicted_unfetched | 64u | Items evicted from LRU that were never | 1404| | | touched by get/incr/append/etc. | 1405| evicted_active | 64u | Items evicted from LRU that had been hit | 1406| | | recently but did not jump to top of LRU | 1407| slab_reassign_running | bool | If a slab page is being moved | 1408| slabs_moved | 64u | Total slab pages moved | 1409| crawler_reclaimed | 64u | Total items freed by LRU Crawler | 1410| crawler_items_checked | 64u | Total items examined by LRU Crawler | 1411| lrutail_reflocked | 64u | Times LRU tail was found with active ref. | 1412| | | Items can be evicted to avoid OOM errors. | 1413| moves_to_cold | 64u | Items moved from HOT/WARM to COLD LRU's | 1414| moves_to_warm | 64u | Items moved from COLD to WARM LRU | 1415| moves_within_lru | 64u | Items reshuffled within HOT or WARM LRU's | 1416| direct_reclaims | 64u | Times worker threads had to directly | 1417| | | reclaim or evict items. | 1418| lru_crawler_starts | 64u | Times an LRU crawler was started | 1419| lru_maintainer_juggles | 1420| | 64u | Number of times the LRU bg thread woke up | 1421| slab_global_page_pool | 32u | Slab pages returned to global pool for | 1422| | | reassignment to other slab classes. | 1423| slab_reassign_rescues | 64u | Items rescued from eviction in page move | 1424| slab_reassign_evictions_nomem | 1425| | 64u | Valid items evicted during a page move | 1426| | | (due to no free memory in slab) | 1427| slab_reassign_chunk_rescues | 1428| | 64u | Individual sections of an item rescued | 1429| | | during a page move. | 1430| slab_reassign_inline_reclaim | 1431| | 64u | Internal stat counter for when the page | 1432| | | mover clears memory from the chunk | 1433| | | freelist when it wasn't expecting to. | 1434| slab_reassign_busy_items | 1435| | 64u | Items busy during page move, requiring a | 1436| | | retry before page can be moved. | 1437| slab_reassign_busy_deletes | 1438| | 64u | Items busy during page move, requiring | 1439| | | deletion before page can be moved. | 1440| log_worker_dropped | 64u | Logs a worker never wrote due to full buf | 1441| log_worker_written | 64u | Logs written by a worker, to be picked up | 1442| log_watcher_skipped | 64u | Logs not sent to slow watchers. | 1443| log_watcher_sent | 64u | Logs written to watchers. | 1444| log_watchers | 64u | Number of currently active watchers. | 1445| unexpected_napi_ids | 64u | Number of times an unexpected napi id is | 1446| | | is received. See doc/napi_ids.txt | 1447| round_robin_fallback | 64u | Number of times napi id of 0 is received | 1448| | | resulting in fallback to round robin | 1449| | | thread selection. See doc/napi_ids.txt | 1450|-----------------------+---------+-------------------------------------------| 1451 1452Settings statistics 1453------------------- 1454CAVEAT: This section describes statistics which are subject to change in the 1455future. 1456 1457The "stats" command with the argument of "settings" returns details of 1458the settings of the running memcached. This is primarily made up of 1459the results of processing commandline options. 1460 1461Note that these are not guaranteed to return in any specific order and 1462this list may not be exhaustive. Otherwise, this returns like any 1463other stats command. 1464 1465|-------------------+----------+----------------------------------------------| 1466| Name | Type | Meaning | 1467|-------------------+----------+----------------------------------------------| 1468| maxbytes | size_t | Maximum number of bytes allowed in the cache | 1469| maxconns | 32 | Maximum number of clients allowed. | 1470| tcpport | 32 | TCP listen port. | 1471| udpport | 32 | UDP listen port. | 1472| inter | string | Listen interface. | 1473| verbosity | 32 | 0 = none, 1 = some, 2 = lots | 1474| oldest | 32u | Age of the oldest honored object. | 1475| evictions | on/off | When off, LRU evictions are disabled. | 1476| domain_socket | string | Path to the domain socket (if any). | 1477| umask | 32 (oct) | umask for the creation of the domain socket. | 1478| shutdown_command | yes/no | If shutdown admin command is enabled. | 1479| growth_factor | float | Chunk size growth factor. | 1480| chunk_size | 32 | Minimum space allocated for key+value+flags. | 1481| num_threads | 32 | Number of threads (including dispatch). | 1482| stat_key_prefix | char | Stats prefix separator character. | 1483| detail_enabled | bool | If yes, stats detail is enabled. | 1484| reqs_per_event | 32 | Max num IO ops processed within an event. | 1485| cas_enabled | bool | When no, CAS is not enabled for this server. | 1486| tcp_backlog | 32 | TCP listen backlog. | 1487| auth_enabled_sasl | yes/no | SASL auth requested and enabled. | 1488| item_size_max | size_t | maximum item size | 1489| maxconns_fast | bool | If fast disconnects are enabled | 1490| hashpower_init | 32 | Starting size multiplier for hash table | 1491| slab_reassign | bool | Whether slab page reassignment is allowed | 1492| slab_automove | bool | Whether slab page automover is enabled | 1493| slab_automove_ratio | 1494| | float | Ratio limit between young/old slab classes | 1495| slab_automove_window | 1496| | 32u | Internal algo tunable for automove | 1497| slab_chunk_max | 32 | Max slab class size (avoid unless necessary) | 1498| hash_algorithm | char | Hash table algorithm in use | 1499| lru_crawler | bool | Whether the LRU crawler is enabled | 1500| lru_crawler_sleep | 32 | Microseconds to sleep between LRU crawls | 1501| lru_crawler_tocrawl | 1502| | 32u | Max items to crawl per slab per run | 1503| lru_maintainer_thread | 1504| | bool | Split LRU mode and background threads | 1505| hot_lru_pct | 32 | Pct of slab memory reserved for HOT LRU | 1506| warm_lru_pct | 32 | Pct of slab memory reserved for WARM LRU | 1507| hot_max_factor | float | Set idle age of HOT LRU to COLD age * this | 1508| warm_max_factor | float | Set idle age of WARM LRU to COLD age * this | 1509| temp_lru | bool | If yes, items < temporary_ttl use TEMP_LRU | 1510| temporary_ttl | 32u | Items with TTL < this are marked temporary | 1511| idle_time | 0 | Drop connections that are idle this many | 1512| | | seconds (0 disables) | 1513| watcher_logbuf_size | 1514| | 32u | Size of internal (not socket) write buffer | 1515| | | per active watcher connected. | 1516| worker_logbuf_size| 32u | Size of internal per-worker-thread buffer | 1517| | | which the background thread reads from. | 1518| read_obj_mem_limit| 32u | Megabyte limit for conn. read/resp buffers. | 1519| track_sizes | bool | If yes, a "stats sizes" histogram is being | 1520| | | dynamically tracked. | 1521| inline_ascii_response | 1522| | bool | Does nothing as of 1.5.15 | 1523| drop_privileges | bool | If yes, and available, drop unused syscalls | 1524| | | (see seccomp on Linux, pledge on OpenBSD) | 1525| proxy_enabled | bool | If proxy has been configured at start | 1526| proxy_uring_enabled | 1527 | bool | If proxy is configured to use IO_URING. | 1528 | | NOTE: uring may be used if kernel too old | 1529| memory_file | char | Warm restart memory file path, if enabled | 1530| client_flags_size | 32u | Size in bytes of client flags | 1531|-------------------+----------+----------------------------------------------| 1532 1533 1534Item statistics 1535--------------- 1536CAVEAT: This section describes statistics which are subject to change in the 1537future. 1538 1539The "stats" command with the argument of "items" returns information about 1540item storage per slab class. The data is returned in the format: 1541 1542STAT items:<slabclass>:<stat> <value>\r\n 1543 1544The server terminates this list with the line 1545 1546END\r\n 1547 1548The slabclass aligns with class ids used by the "stats slabs" command. Where 1549"stats slabs" describes size and memory usage, "stats items" shows higher 1550level information. 1551 1552The following item values are defined as of writing. 1553 1554Name Meaning 1555------------------------------ 1556number Number of items presently stored in this class. Expired 1557 items are not automatically excluded. 1558number_hot Number of items presently stored in the HOT LRU. 1559number_warm Number of items presently stored in the WARM LRU. 1560number_cold Number of items presently stored in the COLD LRU. 1561number_temp Number of items presently stored in the TEMPORARY LRU. 1562age_hot Age of the oldest item in HOT LRU. 1563age_warm Age of the oldest item in WARM LRU. 1564age Age of the oldest item in the LRU. 1565mem_requested Number of bytes requested to be stored in this LRU[*] 1566evicted Number of times an item had to be evicted from the LRU 1567 before it expired. 1568evicted_nonzero Number of times an item which had an explicit expire 1569 time set had to be evicted from the LRU before it 1570 expired. 1571evicted_time Seconds since the last access for the most recent item 1572 evicted from this class. Use this to judge how 1573 recently active your evicted data is. 1574outofmemory Number of times the underlying slab class was unable to 1575 store a new item. This means you are running with -M or 1576 an eviction failed. 1577tailrepairs Number of times we self-healed a slab with a refcount 1578 leak. If this counter is increasing a lot, please 1579 report your situation to the developers. 1580reclaimed Number of times an entry was stored using memory from 1581 an expired entry. 1582expired_unfetched Number of expired items reclaimed from the LRU which 1583 were never touched after being set. 1584evicted_unfetched Number of valid items evicted from the LRU which were 1585 never touched after being set. 1586evicted_active Number of valid items evicted from the LRU which were 1587 recently touched but were evicted before being moved to 1588 the top of the LRU again. 1589crawler_reclaimed Number of items freed by the LRU Crawler. 1590lrutail_reflocked Number of items found to be refcount locked in the 1591 LRU tail. 1592moves_to_cold Number of items moved from HOT or WARM into COLD. 1593moves_to_warm Number of items moved from COLD to WARM. 1594moves_within_lru Number of times active items were bumped within 1595 HOT or WARM. 1596direct_reclaims Number of times worker threads had to directly pull LRU 1597 tails to find memory for a new item. 1598hits_to_hot 1599hits_to_warm 1600hits_to_cold 1601hits_to_temp Number of get_hits to each sub-LRU. 1602 1603Note this will only display information about slabs which exist, so an empty 1604cache will return an empty set. 1605 1606* Items are stored in a slab that is the same size or larger than the 1607 item. mem_requested shows the size of all items within a 1608 slab. (total_chunks * chunk_size) - mem_requested shows memory 1609 wasted in a slab class. If you see a lot of waste, consider tuning 1610 the slab factor. 1611 1612 1613Item size statistics 1614-------------------- 1615CAVEAT: This section describes statistics which are subject to change in the 1616future. 1617 1618The "stats" command with the argument of "sizes" returns information about the 1619general size and count of all items stored in the cache. 1620WARNING: In versions prior to 1.4.27 this command causes the cache server to 1621lock while it iterates the items. 1.4.27 and greater are safe. 1622 1623The data is returned in the following format: 1624 1625STAT <size> <count>\r\n 1626 1627The server terminates this list with the line 1628 1629END\r\n 1630 1631'size' is an approximate size of the item, within 32 bytes. 1632'count' is the approximate amount of items that exist within that 32-byte 1633range. 1634 1635This is essentially a display of all of your items if there was a slab class 1636for every 32 bytes. You can use this to determine if adjusting the slab growth 1637factor would save memory overhead. For example: generating more classes in the 1638lower range could allow items to fit more snugly into their slab classes, if 1639most of your items are less than 200 bytes in size. 1640 1641In 1.4.27 and after, this feature must be manually enabled. 1642 1643It can be enabled at starttime with "-o track_sizes" 1644 1645If disabled, "stats sizes" will return: 1646 1647STAT sizes_status disabled\r\n 1648 1649If an error happens, it will return: 1650 1651STAT sizes_status error\r\n 1652STAT sizes_error [error_message]\r\n 1653 1654NOTE: From 1.4.27 to 1.6.24 this feature could be enabled or disabled at 1655runtime via `stats sizes_enable` and `stats sizes_disable` - however this 1656ability was not thread safe and could crash the server. While possible to fix, 1657it would make the feature too slow to be usable. 1658 1659The feature can still be enabled at start time via `-o track_sizes` and has a 1660low overhead. 1661 1662If you want to make a histogram of item sizes for a memcached instance that is 1663already running, you can use `lru_crawler metadump` and process the output. 1664This command does not block the server. 1665 1666Slab statistics 1667--------------- 1668CAVEAT: This section describes statistics which are subject to change in the 1669future. 1670 1671The "stats" command with the argument of "slabs" returns information about 1672each of the slabs created by memcached during runtime. This includes per-slab 1673information along with some totals. The data is returned in the format: 1674 1675STAT <slabclass>:<stat> <value>\r\n 1676STAT <stat> <value>\r\n 1677 1678The server terminates this list with the line 1679 1680END\r\n 1681 1682|-----------------+----------------------------------------------------------| 1683| Name | Meaning | 1684|-----------------+----------------------------------------------------------| 1685| chunk_size | The amount of space each chunk uses. One item will use | 1686| | one chunk of the appropriate size. | 1687| chunks_per_page | How many chunks exist within one page. A page by | 1688| | default is less than or equal to one megabyte in size. | 1689| | Slabs are allocated by page, then broken into chunks. | 1690| total_pages | Total number of pages allocated to the slab class. | 1691| total_chunks | Total number of chunks allocated to the slab class. | 1692| get_hits | Total number of get requests serviced by this class. | 1693| cmd_set | Total number of set requests storing data in this class. | 1694| delete_hits | Total number of successful deletes from this class. | 1695| incr_hits | Total number of incrs modifying this class. | 1696| decr_hits | Total number of decrs modifying this class. | 1697| cas_hits | Total number of CAS commands modifying this class. | 1698| cas_badval | Total number of CAS commands that failed to modify a | 1699| | value due to a bad CAS id. | 1700| touch_hits | Total number of touches serviced by this class. | 1701| used_chunks | How many chunks have been allocated to items. | 1702| free_chunks | Chunks not yet allocated to items, or freed via delete. | 1703| free_chunks_end | Number of free chunks at the end of the last allocated | 1704| | page. | 1705| active_slabs | Total number of slab classes allocated. | 1706| total_malloced | Total amount of memory allocated to slab pages. | 1707|-----------------+----------------------------------------------------------| 1708 1709 1710Connection statistics 1711--------------------- 1712The "stats" command with the argument of "conns" returns information 1713about currently active connections and about sockets that are listening 1714for new connections. The data is returned in the format: 1715 1716STAT <file descriptor>:<stat> <value>\r\n 1717 1718The server terminates this list with the line 1719 1720END\r\n 1721 1722The following "stat" keywords may be present: 1723 1724|---------------------+------------------------------------------------------| 1725| Name | Meaning | 1726|---------------------+------------------------------------------------------| 1727| addr | The address of the remote side. For listening | 1728| | sockets this is the listen address. Note that some | 1729| | socket types (such as UNIX-domain) don't have | 1730| | meaningful remote addresses. | 1731| listen_addr | The address of the server. This field is absent | 1732| | for listening sockets. | 1733| state | The current state of the connection. See below. | 1734| secs_since_last_cmd | The number of seconds since the most recently | 1735| | issued command on the connection. This measures | 1736| | the time since the start of the command, so if | 1737| | "state" indicates a command is currently executing, | 1738| | this will be the number of seconds the current | 1739| | command has been running. | 1740|---------------------+------------------------------------------------------| 1741 1742The value of the "state" stat may be one of the following: 1743 1744|----------------+-----------------------------------------------------------| 1745| Name | Meaning | 1746|----------------+-----------------------------------------------------------| 1747| conn_closing | Shutting down the connection. | 1748| conn_listening | Listening for new connections or a new UDP request. | 1749| conn_mwrite | Writing a complex response, e.g., to a "get" command. | 1750| conn_new_cmd | Connection is being prepared to accept a new command. | 1751| conn_nread | Reading extended data, typically for a command such as | 1752| | "set" or "put". | 1753| conn_parse_cmd | The server has received a command and is in the middle | 1754| | of parsing it or executing it. | 1755| conn_read | Reading newly-arrived command data. | 1756| conn_swallow | Discarding excess input, e.g., after an error has | 1757| | occurred. | 1758| conn_waiting | A partial command has been received and the server is | 1759| | waiting for the rest of it to arrive (note the difference | 1760| | between this and conn_nread). | 1761| conn_write | Writing a simple response (anything that doesn't involve | 1762| | sending back multiple lines of response data). | 1763|----------------+-----------------------------------------------------------| 1764 1765TLS statistics 1766-------------- 1767 1768TLS is a compile-time opt-in feature available in versions 1.5.13 and later. 1769When compiled with TLS support and TLS termination is enabled at runtime, the 1770following additional statistics are available via the "stats" command. 1771 1772|--------------------------------+----------+--------------------------------| 1773| Name | Type | Meaning | 1774|--------------------------------+----------+--------------------------------| 1775| ssl_handshake_errors | 64u | Number of times the server has | 1776| | | encountered an OpenSSL error | 1777| | | during handshake (SSL_accept). | 1778| ssl_proto_errors | 64u | Number of times a client has | 1779| | | seen a fatal TLS protocol error| 1780| ssl_min_version | char | Minimum supported TLS version | 1781| | | for client handshakes. | 1782| ssl_new_sessions | 64u | When SSL session caching is | 1783| | | enabled, the number of newly | 1784| | | created server-side sessions. | 1785| | | Available only when compiled | 1786| | | with OpenSSL 1.1.1 or newer. | 1787| time_since_server_cert_refresh | 32u | Number of seconds that have | 1788| | | elapsed since the last time | 1789| | | certs were reloaded from disk. | 1790|--------------------------------+----------+--------------------------------| 1791 1792 1793Other commands 1794-------------- 1795 1796"flush_all" is a command with an optional numeric argument. It always 1797succeeds, and the server sends "OK\r\n" in response (unless "noreply" 1798is given as the last parameter). Its effect is to invalidate all 1799existing items immediately (by default) or after the expiration 1800specified. After invalidation none of the items will be returned in 1801response to a retrieval command (unless it's stored again under the 1802same key *after* flush_all has invalidated the items). flush_all 1803doesn't actually free all the memory taken up by existing items; that 1804will happen gradually as new items are stored. The most precise 1805definition of what flush_all does is the following: it causes all 1806items whose update time is earlier than the time at which flush_all 1807was set to be executed to be ignored for retrieval purposes. 1808 1809The intent of flush_all with a delay, was that in a setting where you 1810have a pool of memcached servers, and you need to flush all content, 1811you have the option of not resetting all memcached servers at the 1812same time (which could e.g. cause a spike in database load with all 1813clients suddenly needing to recreate content that would otherwise 1814have been found in the memcached daemon). 1815 1816The delay option allows you to have them reset in e.g. 10 second 1817intervals (by passing 0 to the first, 10 to the second, 20 to the 1818third, etc. etc.). 1819 1820"cache_memlimit" is a command with a numeric argument. This allows runtime 1821adjustments of the cache memory limit. It returns "OK\r\n" or an error (unless 1822"noreply" is given as the last parameter). If the new memory limit is higher 1823than the old one, the server may start requesting more memory from the OS. If 1824the limit is lower, and slabs_reassign+automove are enabled, free memory may 1825be released back to the OS asynchronously. 1826 1827The argument is in megabytes, not bytes. Input gets multiplied out into 1828megabytes internally. 1829 1830"shutdown" is a command with an optional argument used to stop memcached with 1831a kill signal. By default, "shutdown" alone raises SIGINT, though "graceful" 1832may be specified as the single argument to instead trigger a graceful shutdown 1833with SIGUSR1. The shutdown command is disabled by default, and can be enabled 1834with the -A/--enable-shutdown flag. 1835 1836"version" is a command with no arguments: 1837 1838version\r\n 1839 1840In response, the server sends 1841 1842"VERSION <version>\r\n", where <version> is the version string for the 1843server. 1844 1845"verbosity" is a command with a numeric argument. It always succeeds, 1846and the server sends "OK\r\n" in response (unless "noreply" is given 1847as the last parameter). Its effect is to set the verbosity level of 1848the logging output. 1849 1850"quit" is a command with no arguments: 1851 1852quit\r\n 1853 1854Upon receiving this command, the server closes the 1855connection. However, the client may also simply close the connection 1856when it no longer needs it, without issuing this command. 1857 1858Security restrictions 1859--------------------- 1860 1861In the debug build the following commands are available for testing the 1862security restrictions: 1863 1864"misbehave" is a command with no arguments: 1865 1866misbehave\r\n 1867 1868This command causes the worker thread to attempt a) opening a new socket, and 1869b) executing a shell command. If either one is successful, an error is 1870returned. Otherwise memcached returns OK. 1871The check is available only in Linux builds with seccomp enabled. 1872 1873 1874UDP protocol 1875------------ 1876 1877For very large installations where the number of clients is high enough 1878that the number of TCP connections causes scaling difficulties, there is 1879also a UDP-based interface. The UDP interface does not provide guaranteed 1880delivery, so should only be used for operations that aren't required to 1881succeed; typically it is used for "get" requests where a missing or 1882incomplete response can simply be treated as a cache miss. 1883 1884Each UDP datagram contains a simple frame header, followed by data in the 1885same format as the TCP protocol described above. In the current 1886implementation, requests must be contained in a single UDP datagram, but 1887responses may span several datagrams. (The only common requests that would 1888span multiple datagrams are huge multi-key "get" requests and "set" 1889requests, both of which are more suitable to TCP transport for reliability 1890reasons anyway.) 1891 1892The frame header is 8 bytes long, as follows (all values are 16-bit integers 1893in network byte order, high byte first): 1894 18950-1 Request ID 18962-3 Sequence number 18974-5 Total number of datagrams in this message 18986-7 Reserved for future use; must be 0 1899 1900The request ID is supplied by the client. Typically it will be a 1901monotonically increasing value starting from a random seed, but the client 1902is free to use whatever request IDs it likes. The server's response will 1903contain the same ID as the incoming request. The client uses the request ID 1904to differentiate between responses to outstanding requests if there are 1905several pending from the same server; any datagrams with an unknown request 1906ID are probably delayed responses to an earlier request and should be 1907discarded. 1908 1909The sequence number ranges from 0 to n-1, where n is the total number of 1910datagrams in the message. The client should concatenate the payloads of the 1911datagrams for a given response in sequence number order; the resulting byte 1912stream will contain a complete response in the same format as the TCP 1913protocol (including terminating \r\n sequences). 1914