Built-in proxy quickstart
This page helps you get familiar with the Memcached built-in proxy by guiding you through the following tasks:
- Build Memcached with its proxy features enabled.
- Download the Lua library that the proxy requires for common tasks.
- Set up a minimal proxy configuration file that lets the proxy use two Memcached servers as its backend.
- Run this proxy-based Memcached architecture, and observe the proxy at work by connecting to it and querying it.
For a general overview of the Memcached built-in proxy, see Built-in proxy.
Before you begin
Make sure that your machine has the necessary development tools and libraries to build Memcached from source. These requirements are probably available from your operating system’s package manager.
For example, on Debian, you can satisfy these requirements by having the following packages installed:
gcc
make
libevent-dev
The steps on this page guide you though launching three Memcached servers on TCP ports 11211
, 11212
, and 11213
. If you already have Memcached services running on those ports and you don’t want to disrupt them, then you should take either of these additional steps:
- Substitute different port numbers for this tutorial.
- Run this tutorial as written on a different machine that isn’t running Memcached.
Download and build the proxy
Because the Memcached built-in proxy is a non-default, compile-time configuration option, the proxy is available as a Memcached feature only if you build Memcached from source. To do this, follow these steps:
Download the latest Memcached release tarball:
wget https://memcached.org/latest
Unzip and untar the tarball, then change your working directory to the source directory:
tar xzvf memcached-VERSION.tar.gz cd memcached-VERSION
Replace
VERSION
with the version number in the tarball that you downloaded in the previous step.Configure the Memcached build process to enable the built-in proxy:
./configure --enable-proxy
Build and test Memcached:
make make test
If you encounter errors related to missing tools or libraries, make sure that your system has the development packages that you need to build Memcached from source. For more information, see “Before you begin”, earlier on this page.
Note: For the sake of simplicity and easier cleanup, this quick-start guide doesn’t include a
make install
step. If you want to install the proxy-enabled Memcached on this machine, then you can do as a final step at the end of this guide.
Configure the proxy
To create a minimal proxy configuration file named config.lua
, run the following command:
echo 'pools{
quickstart_pool = {
backends = {
"127.0.0.1:11212",
}
},
fallback = {
backends = {
"127.0.0.1:11213",
}
}
}
routes{
map = {
quickstart = route_direct{
child = "quickstart_pool",
},
},
default = route_direct{ child = "fallback" }
}' > config.lua
Set up and run the proxied Memcached servers
Using the binary that you built in a previous step, launch two ordinary Memcached cache servers, running on TCP ports
11212
and11213
:./memcached -l localhost -p 11212 & ./memcached -l localhost -p 11213 &
Launch a third Memcached server in proxy mode, by specifying the proxy-specific configuration file that you created, in previous steps:
./memcached -l localhost -p 11211 -o proxy_config=routelib,proxy_arg=config.lua &
Connect to and use the proxy
Connect to the proxy and set a variable:
telnet localhost 11211 set quickstart/data 0 0 6 Hello!
The Memcached proxy responds with
STORED
.Fetch the data again:
get quickstart/data
The Memcached proxy responds with the following:
Hello! END
Terminate the Telnet session:
Press Ctrl + ].
At the
telnet>
prompt, enterquit
.
At this point, you can optionally connect to the two Memcached backend servers by connecting to ports 11212
and 11213
and running the command get quickstart/data
on both. One of the two servers returns the value Hello!
. That server is the one that the proxy chose as the backend to store the data under the quickstart/data
key.
Clean up
When you are finished with this tutorial, you can stop the three Memcached processes that you launched in the previous steps. You can do this by repeatedly running fg
then pressing ctrl-c until all instances are stopped.
Because this quickstart didn’t have you install the Memcached software that you built, you can clean up by deleting the source directory that you downloaded.
If you want to keep the Memcached software that you built with the proxy features enabled, then you can install it through one of these methods:
Install Memcached in the default location on your file system, such as
/usr/local/bin
, by runningsudo make install
.Manually copy or move the
memcached
binary to the location of your choice.
You also have the option of rebuilding the memcached
binary with different configuration options. For more information, run the command ./configure --help
from within the Memcached source directory.