Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 157 lines (122 sloc) 7.896 kB
fff5726 @caniszczyk Add Travis CI Support
caniszczyk authored
1 # twemproxy (nutcracker) [![Build Status](https://secure.travis-ci.org/twitter/twemproxy.png)](http://travis-ci.org/twitter/twemproxy)
3ca2e51 Initial commit
Manju Rajashekhar authored
2
3 **twemproxy** (pronounced "two-em-proxy"), aka **nutcracker** is a fast and lightweight proxy for memcached protocol. It was primarily built to reduce the connection count on the backend caching servers.
4
5 ## Build ##
6
7 To build nutcracker from distribution tarball:
8
9 $ ./configure
10 $ make
11 $ sudo make install
12
13 To build nutcracker from distribution tarball in _debug mode_:
14
15 $ CFLAGS="-ggdb3 -O0" ./configure --enable-debug=full
16 $ make
17 $ sudo make install
18
19 To build nutcracker from source with _debug logs enabled_ and _assertions disabled_:
20
21 $ git clone git@github.com:twitter/twemproxy.git
22 $ cd twemproxy
23 $ autoreconf -fvi
24 $ ./configure --enable-debug=log
25 $ make
26 $ src/nutcracker -h
27
28 ## Features ##
29
30 + Fast.
31 + Lightweight.
32 + Maintains persistent server connections.
33 + Keeps connection count on the backend caching servers low.
34 + Enables pipelining of memcached requests and responses.
35 + Supports proxying to multiple servers.
36 + Supports multiple server pools simultaneously.
37 + Implements the complete memcached ASCII protocol.
38 + Easy configuration of server pools through a YAML file.
39 + Supports multiple hashing modes including consistent hashing and distribution.
40 + Observability through stats exposed on stats monitoring port.
41
42 ## Help ##
43
44 Usage: nutcracker [-?hVdt] [-v verbosity level] [-o output file]
45 [-c conf file] [-s stats port] [-i stats interval]
c9d0c17 command line option to set mbuf chunk size
Manju Rajashekhar authored
46 [-p pid file] [-m mbuf size]
3ca2e51 Initial commit
Manju Rajashekhar authored
47
48 Options:
49 -h, --help : this help
50 -V, --version : show version and exit
51 -t, --test-conf : test configuration for syntax errors and exit
52 -d, --daemonize : run as a daemon
53 -v, --verbosity=N : set logging level (default: 5, min: 0, max: 11)
54 -o, --output=S : set logging file (default: stderr)
55 -c, --conf-file=S : set configuration file (default: conf/nutcracker.yml)
56 -s, --stats-port=N : set stats monitoring port (default: 22222)
57 -i, --stats-interval=N : set stats aggregation interval in msec (default: 30000 msec)
58 -p, --pid-file=S : set pid file (default: off)
c9d0c17 command line option to set mbuf chunk size
Manju Rajashekhar authored
59 -m, --mbuf-size=N : set size of mbuf chunk in bytes (default: 16384 bytes)
3ca2e51 Initial commit
Manju Rajashekhar authored
60
61 ## Configuration ##
62
63 nutcracker can be configured through a YAML file specified by the -c or --conf-file command-line argument on process start. The configuration file is used to specify the server pools and the servers within each pool that nutcracker manages. The configuration files parses and understands the following keys:
64
65 + **listen**: The listening address and port (name:port or ip:port) for this server pool.
66 + **hash**: The name of the hash function. Possible values are: one_at_a_time, md5, crc32, fnv1_64, fnv1a_64, fnv1_32, fnv1a_32, hsieh, murmur, and jenkins.
67 + **distribution**: The key distribution mode. Possible values are: ketama, modula and random.
68 + **timeout**: The timeout value in msec that we wait for to establish a connection to the server or receive a response from a server. By default, we wait indefinitely.
69 + **backlog**: The TCP backlog argument. Defaults to 512.
70 + **preconnect**: A boolean value that controls if nutcracker should preconnect to all the servers in this pool on process start. Defaults to false.
71 + **server_connections**: The maximum number of connections that can be opened to each server. By default, we open at most 1 server connection.
72 + **auto_eject_hosts**: A boolean value that controls if server should be ejected temporarily when it fails consecutively server_failure_limit times. Defaults to false.
73 + **server_retry_timeout**: The timeout value in msec to wait for before retrying on a temporarily ejected server, when auto_eject_host is set to true. Defaults to 30000 msec.
74 + **server_failure_limit**: The number of conseutive failures on a server that would leads to it being temporarily ejected when auto_eject_host is set to true. Defaults to 2.
75 + **servers**: A list of server address, port and weight (name:port:weight or ip:port:weight) for this server pool.
76
77 For example, the configuration file in conf/nutcracker.yml, also shown below, configures 4 server pools with names - _alpha_, _beta_, _gamma_ and _delta_. Clients that intend to send requests to one of the 10 servers in pool gamma connect to port 22123 on 127.0.0.1. Clients that intend to send request to one of 2 servers in pool delta connect to unix path /tmp/gamma. Requests sent to pool alpha and delta have no timeout and might require timeout functionality to be implemented on the client side. On the other hand, requests sent to pool beta and gamma timeout after 400 msec and 100 msec respectively when no response is received from the server. Of the 4 server pools, only pools alpha, beta and gamma are configured to use server ejection and hence are resilient to server failures. All the 4 server pools use ketama consistent hashing for key distribution with the key hasher for pools alpha, beta and gamma set to fnv1a_64 while that for pool delta set to hsieh.
78
79 alpha:
80 listen: 127.0.0.1:22121
81 hash: fnv1a_64
82 distribution: ketama
83 auto_eject_hosts: true
84 server_retry_timeout: 2000
85 server_failure_limit: 1
86 servers:
87 - 127.0.0.1:11211:1
88
89 beta:
90 listen: 127.0.0.1:22122
91 hash: fnv1a_64
92 distribution: ketama
93 timeout: 400
94 backlog: 1024
95 preconnect: true
96 auto_eject_hosts: true
97 server_retry_timeout: 2000
98 server_failure_limit: 3
99 servers:
100 - 127.0.0.1:11212:1
101 - 127.0.0.1:11213:1
102
103 gamma:
104 listen: 127.0.0.1:22123
105 hash: fnv1a_64
106 distribution: ketama
107 timeout: 100
108 auto_eject_hosts: true
109 server_retry_timeout: 2000
110 server_failure_limit: 1
111 servers:
112 - 127.0.0.1:11214:1
113 - 127.0.0.1:11215:1
114 - 127.0.0.1:11216:1
115 - 127.0.0.1:11217:1
116 - 127.0.0.1:11218:1
117 - 127.0.0.1:11219:1
118 - 127.0.0.1:11220:1
119 - 127.0.0.1:11221:1
120 - 127.0.0.1:11222:1
121 - 127.0.0.1:11223:1
122
123 delta:
124 listen: /tmp/gamma
125 hash: hsieh
126 distribution: ketama
127 auto_eject_hosts: false
128 servers:
129 - 127.0.0.1:11214:100000
130 - 127.0.0.1:11215:1
131
132 Finally, to make writing syntactically correct configuration file easier, nutcracker provides a command-line argument -t or --test-conf that can be used to test the YAML configuration file for any syntax error.
133
134 ## Observability ##
135
136 Observability in nutcracker is through logs and stats.
137
138 Nutcracker exposes stats at the granularity of server pool and servers per pool through the stats monitoring port. The stats are essentially JSON formatted key-value pairs, with the keys corresponding to counter names. By default stats are exposed on port 22222 and aggregated every 30 seconds. Both these values can be configured on program start using the -c or --conf-file and -i or --stats-interval command-line arguments respectively.
139
140 Logging in nutcracker is only available when nutcracker is built with logging enabled. By default logs are written to stderr. Nutcracker can also be configured to write logs to a specific file through the -o or --output command-line argument. On a running nutcracker, we can turn log levels up and down by sending it SIGTTIN and SIGTTOU signals respectively and reopen log files by sending it SIGHUP signal.
141
142 ## Issues and Support ##
143
144 Have a bug or a question? Please create an issue here on GitHub!
145
146 https://github.com/twitter/twemproxy/issues
147
148 ## Contributors ##
149
4337239 updated readme
Manju Rajashekhar authored
150 * Manju Rajashekhar ([@manju](https://twitter.com/manju))
3ca2e51 Initial commit
Manju Rajashekhar authored
151
152 ## License ##
153
154 Copyright 2012 Twitter, Inc.
155
156 Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0
Something went wrong with that request. Please try again.