Memproxy

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.

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 before custom allocator (after building memproxy of the appropriate bit size):

# export LD_PRELOAD=libmemproxy.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:lib_custom_alloc_name.so" > /etc/ld.so.preload

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

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

Notes

Please note that memproxy is a plugin for custom allocator. If you don't load the allocator, it will crash because the library object cannot be constructed. Also, if it is not possible to load libC for your platform, it will also 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.

Restrictions

For technical reasons, I had to refuse to display error messages when checking the loading of the allocator and libC libraries. Any output statements contain malloc under the hood and lead to recursion. Thus, when segfaulting at startup, the first thing to check is that LD_PRELOAD is correct.

---