Memproxy

This repository is archived and is no longer being developed.

Concepts

Memproxy is designed to route requests for memory allocation and deallocation as a plugin to custom allocator. It is intended to handle exceptions - applications whose allocation requests must be routed to the system allocator.

The principle of operation lies in the global preloading of the proxy before the custom allocator. When loading, the library determines the name of the executable file that initiated the loading and checks it against the exclusion list specified in the configuration file.

If the filename is in the list, a boolean flag is set and all allocation/deallocation requests are redirected to the system allocator.

If the application is not on the exclusion list, allocation requests are processed in the standard way for the custom allocator, according to the list of the custom allocator wrapper.

Build and installation

Build memproxy

To make and install memproxy run:

# ./configure 'CXXFLAGS=-m64'

or

# ./configure 'CXXFLAGS=-m32'

then

# make
# make install-strip

Installation prefix by default is /usr/local. Logging library libmemproxy.so will install into $PREFIX/lib.

Using memproxy

Prerequisites

Most modern OS require to permit libraries/path to be used with LD_PRELOAD. To run libmemproxy, make sure you configured access to installation directory for dynamic linker.

Some examples:

Solaris

Run (for 32 bit memproxy):

# crle -c /var/ld/ld.config -l /lib:/usr/lib:/usr/local/lib -s /lib/secure:/usr/lib/secure:/usr/lib:/usr/local/lib

and/or (for 64 bit memproxy):

# crle -64 -c /var/ld/64/ld.config -l /lib/64:/usr/lib/64:/usr/local/lib -s /lib/secure/64:/usr/lib/secure/64:/usr/local/lib

Linux

Run the command:

# echo "/usr/local/lib" > /etc/ld.so.conf.d/memproxy.conf

then run ldconfig as root or reboot your machine

or

add /usr/local/lib to /etc/ld.so.conf, then run ldconfig as root.

FreeBSD/OpenBSD

As root execute command:

# ldconfig -R /usr/local/lib

and then run ldconfig as root or reboot system.

Note: A custom allocator can have its own prerequisites.

Running memproxy

After the preparation is complete, you are ready to proxify your application.

Since the easiest way to intercept memory allocation functions cross-platform is to use LD_PRELOAD, you must load the proxy library first before libc and custom allocator (after building memproxy of the appropriate bit size) exactly in that order:

# export LD_PRELOAD=libmemproxy.so:/usr/lib/libc.so:lib_custom_alloc_name.so

where lib_custom_alloc_name is, for example, libjemalloc.

Note: Some platforms uses LD_PRELOAD_32/LD_PRELOAD_64/LDR_PRELOAD/LDR_PRELOAD64 environment variables instead.

The recommended practice, however, is to use memproxy globally (if the operating system allows it), in the /etc/ld.so.preload preload list.

In this case, the /etc/ld.so.preload file should contain two entries, as shown below:

# echo "libmemproxy.so:/usr/lib/libc.so:lib_custom_alloc_name.so" > \
	/etc/ld.so.preload

Important - you must specify either symbolic link or full absolute path to libc. To determine it, run the command:

# find / -name libc.so.*

Remember, you need to select the library of the correct bit depth (in case of multilib).

libc must be explicitly preloaded because custom allocators also interpose malloc/free/realloc/calloc functions that will be found by the dynamic loader earlier than libc functions, which are usually loaded much further from the beginning of the dependency list.

With the specified preload sequence and the correct definition of the custom allocator's internal API functions, allocation calls will be correctly routed depending on the g_Exists flag.

In some cases, you may need to add the full absolute path to the libraries.

Also keep in mind you must edit custom allocator API function names in accordance with the API of the preloaded allocator in memproxy.h.

Note 1: Do not define interposed malloc/realloc/free etc. Use internal API instead.

Note 2: malloc_trim is absent in many implementations of custom allocators, so we do not check for the presence of the function. Accordingly, dlsym will return a null pointer and interposition of the corresponding function will not work.

Configuration

Exclusion list is defined in $(CONFIG_DIR)/memproxy.conf. The configuration file is a list of executable binary file names (no absolute or relative path), consecutively, separated by a carriage return. Note that CR/LF is not allowed; if such characters are present in the configuration file, all or part of the values will be silently ignored.

Config contents example:

#ls
;df
;du
top
telegram
wget

Note: Strings starting from # or ; threats as comment and will be ignored.

Notes

Please note that memproxy is a plugin for custom allocator. If memproxy can't load the allocator, it will use own libC dependency. Also, if it is not possible to load libC for your platform, it can not work (but not nesessary crash). In this case, you need to check the name of the libC library and, if necessary, adjust the corresponding macro in the source code.