Skip navigation links
14.5.2.1 memcached Deployment »
Section Navigation      [Toggle]

14.5.2. Using memcached

[+/-]

14.5.2.1. memcached Deployment
14.5.2.2. Using namespaces
14.5.2.3. Data Expiry
14.5.2.4. memcached Hashing/Distribution Types
14.5.2.5. Using memcached and DTrace
14.5.2.6. Memory allocation within memcached
14.5.2.7. memcached thread Support
14.5.2.8. memcached Logs

To start using memcached, you must start the memcached service on one or more servers. Running memcached sets up the server, allocates the memory and starts listening for connections from clients.

Note

You do not need to be privileged user (root) to run memcached unless you want to listen on one of the privileged TCP/IP ports (below 1024). You must, however, use a user that has not had their memory limits restricted using setrlimit or similar.

To start the server, run memcached as a nonprivileged (that is, non-root) user: 

shell> memcached

By default, memcached uses the following settings:

  • Memory allocation of 64MB

  • Listens for connections on all network interfaces, using port 11211

  • Supports a maximum of 1024 simultaneous connections

Typically, you would specify the full combination of options that you want when starting memcached, and normally provide a startup script to handle the initialization of memcached. For example, the following line starts memcached with a maximum of 1024MB RAM for the cache, listening on port 11121 on the IP address 192.168.0.110, running has a background daemon: 

shell> memcached -d -m 1024 -p 11121 -l 192.168.0.110

To ensure that memcached is started up on boot you should check the init script and configuration parameters. On OpenSolaris, memcached is controlled by SMF. You can enable it by using: 

root-shell> svcadm enable memcached

memcached supports the following options:

  • -u user

    If you start memcached as root, use the -u option to specify the user for executing memcached: 

    shell> memcached -u memcache

  • -m memory

    Set the amount of memory allocated to memcached for object storage. Default is 64MB.

    To increase the amount of memory allocated for the cache, use the -m option to specify the amount of RAM to be allocated (in megabytes). The more RAM you allocate, the more data you can store and therefore the more effective your cache will be.

    Warning

    Do not specify a memory allocation larger than your available RAM. If you specify too large a value, then some RAM allocated for memcached will be using swap space, and not physical RAM. This may lead to delays when storing and retrieving values, because data will be swapped to disk, instead of storing the data directly in RAM.

    You can use the output of the vmstat command to get the free memory, as shown in free column: 

    shell> vmstat
kthr      memory            page            disk          faults      cpu
r b w   swap  free  re  mf pi po fr de sr s1 s2 -- --   in   sy   cs us sy id
0 0 0 5170504 3450392 2  7  2  0  0  0  4  0  0  0  0  296   54  199  0  0 100

    For example, to allocate 3GB of RAM: 

    shell> memcached -m 3072

    On 32-bit x86 systems where you are using PAE to access memory above the 4GB limit, you will be unable to allocate RAM beyond the maximum process size. You can get around this by running multiple instances of memcached, each listening on a different port: 

    shell> memcached -m 1024 -p11211
shell> memcached -m 1024 -p11212
shell> memcached -m 1024 -p11213

    Note

    On all systems, particularly 32-bit, you should ensure that you leave enough room for both memcached application in addition to the memory setting. For example, if you have a dedicated memcached host with 4GB of RAM you should not set the memory size above 3500MB. Failure to do this may cause either a crash or severe performance issues.

  • -l interface

    Specify a network interface/address to listen for connections. The default is to listen on all available address (INADDR_ANY). 

    shell> memcached -l 192.168.0.110

    Support for IPv6 address support was added in memcached 1.2.5.

  • -p port

    Specify the TCP port to use for connections. Default is 18080. 

    shell> memcached -p 18080

  • -U port

    Specify the UDP port to use for connections. Default is 11211, 0 switches UDP off. 

    shell> memcached -U 18080

  • -s socket

    Specify a Unix socket to listen on.

    If you are running memcached on the same server as the clients, you can disable the network interface and use a local UNIX socket using the -s option: 

    shell> memcached -s /tmp/memcached

    Using a UNIX socket automatically disables network support, and saves network ports (allowing more ports to be used by your web server or other process).

  • -a mask

    Specify the access mask to be used for the Unix socket, in octal. Default is 0700.

  • -c connections

    Specify the maximum number of simultaneous connections to the memcached service. The default is 1024. 

    shell> memcached -c 2048

    You should use this option, either to reduce the number of connections (to prevent overloading memcached service) or to increase the number to make more effective use of the server running memcached server.

  • -t threads

    Specify the numnber of threads to use when processing incoming requests.

    By default, memcached is configured to use 4 concurrent threads. The threading improves the performance of storing and retrieving data in the cache, using a locking system to prevent different threads overwriting or updating the same values. You may want to increase or decrease the number of threads, use the -t option: 

    shell> memcached -t 8

  • -d

    Run memcached as a daemon (background) process: 

    shell> memcached -d

  • -r

    Maximize the size of the core file limit. In the event of a failure, this will attempt to dump the entire memory space to disk as a core file, up to any limits imposed by setrlimit.

  • -M

    Return an error to the client when the memory has been exhausted. This replaces the normal behavior of removing older items from the cache to make way for new items.

  • -k

    Lock down all paged memory. This reserves the memory before use, instead of allocating new slabs of memory as new items are stored in the cache.

    Note

    There is a user-level limit on how much memory you may lock. Trying to allocate more than the available memory will fail. You can set the limit for the user you started the daemon with (not for the -u user user) within the shell by using ulimit -S -l NUM_KB

  • -v

    Verbose mode. Prints errors and warnings while executing the main event loop.

  • -vv

    Very verbose mode. In addition to information printed by -v, also prints each client command and the response.

  • -vvv

    Extremely verbose mode. In addition to information printed by -vv, also show the internal state transitions.

  • -h

    Print the help message and exit.

  • -i

    Print the memcached and libevent license.

  • -I mem

    Specify the maximum size allowed for storing an object within the memcached instance. The size supports a unit postix (k for kilobytes, m for megabytes). For example, to increase the maximum supported object size to 32MB: 

    shell> memcached -I 32m

    The maximum object size you can specify is 128MB, the default remains at 1MB.

    This option was added in 1.4.2.

  • -b

    Set the backlog queue limit. The backlog queue configures how many network connections can be waiting to be processed by memcached. Increasing this limit may reduce errors received by the client that it is not able to connect to the memcached instance, but will not improve the performance of the server. The default is 1024.

  • -P pidfile

    Save the process ID of the memcached instance into file.

  • -f

    Set the chunk size growth factor. When allocating new memory chunks, the allocated size of new chunks will be determined by multiplying the default slab size by this factor.

    To see the effects of this option without extensive testing, use the -vv command-line option to show the calculated slab sizes. For more information, see Section 14.5.2.8, “memcached Logs”.

  • -n bytes

    The minimum space allocated for the key+value+flags information. The default is 48 bytes.

  • -L

    On systems that support large memory pages, enables large memory page use. Using large memory pages enables memcached to allocate the item cache in one large chunk, which can improve the performance by reducing the number misses when accessing memory.

  • -C

    Disable the use of compare and swap (CAS) operations.

    This option was added in memcached 1.3.x.

  • -D char

    Set the default character to be used as a delimiter between the key prefixes and IDs. This is used for the per-prefix statistics reporting (see Section 14.5.4, “Getting memcached Statistics”). The default is the colon (:). If this option is used, statistics collection is turned on automatically. If not used, you can enable stats collection by sending the stats detail on command to the server.

    This option was added in memcached 1.3.x.

  • -R num

    Sets the maximum number of requests per event process. The default is 20.

  • -B protocol

    Set the binding protocol, that is, the default memcached protocol support for client connections. Options are ascii, binary or auto. Automatic (auto) is the default.

    This option was added in memcached 1.4.0.