vikasnkumar · October 9, 2011 16:05
diff --git a/gistfile1.txt b/gistfile1.txt
 Introduction to Hotpatch
 =========================
 Hotpatch is a library that can be used to dynamically load a shared library
 (.so) file on Linux from one process into another already running process,
 without affecting the execution of the target process. The API is a C API, but
 also supported in C++.

 The current version is 0.2.

 The limitations, directions on how to use, and possible uses of hotpatch will be
 explained in this document.

 The main idea of hotpatch stems from the fact that in Linux, it is not easy to
 load a library into another already running process. In Windows, there is an API
 called CreateRemoteThread() that can load a library into another process very
 easily with a couple of API calls. Hotpatch makes this functionality available
 to Linux users and developers, with a single API call. Unlike other available
 injection libraries, hotpatch restores the execution of the process to its
 original state.

 The user can do the following with hotpatch:
 - load his/her own .so file into an already running process
 - invoke a custom symbol/function in that .so file
 - pass arguments to that function as long as it is serialized to the form of a
  byte buffer and length of the buffer. This shall be explained more later.

 Hotpatch is available as an API with a header file called "hotpatch.h" and a
 .so file called "libhotpatch.so", and also a commandline application called
 "hotpatcher" which can inject .so files into processes via the commandline
 itself. Hotpatch also comes with a test .so called "libhotpatchtest.so"
 which can be used via the commandline "hotpatcher" application to test out
 the working of hotpatch on any system. The "libhotpatchtest.so" has a symbol
 "mysym" that can be invoked, and it writes to the "/tmp/hotpatchtest.log" file
 with the timestamp at which the .so file was injected and anything else.

 Limitations
 ============
 NOTE: If hotpatch is compiled in 64-bit mode, it can inject only into 64-bit processes, and if compiled in 32-bit mode it can inject into 32-bit processes only.

 There are some limitations, the main being that the user can inject a library
 .so file only in a process on which the user has privileges over. For example,
 as the root user, hotpatch can inject libraries into any process, but as a
 regular non-root user, hotpatch can inject libraries into only those processes
 that hotpatch has access to, i.e. the user's processes and any other via sudo
 privileges.

 The other limitation is that if the user needs to compile his shared library
 with the linker options "-fPIC -nostartfiles" so that hotpatch can reliably load
 the .so file. If this is not available to the user, then the user needs to explicitly provide the symbol he/she wants to invoke in the target process.

 Another limitation is that injection for a particular .so file can happen only
 once in the target process. Each library that is injected can be injected only
 once into the target process.

 Usage: API
 ===========

 The "hotpatch.h" header file needs to be included by the user. There are 3 main
 API calls that matter. Each of them have to be called in the order as shown
 below in the sample program.

 - hotpatch_t *hotpatch_create(pid_t pid, int verbose);

 This function takes a PID of the target process, and the verbosity level
 (between 0 to 6), and returns an opaque object which contains further intimate
 details about the process such as current library mappings, and locations of the
 important functions needed for hotpatch to do its work.

 - int hotpatch_inject_library(hotpatch_t *hp,
 							  const char *sofile,
 							  const char *symbol,
 							  const unsigned char *data,
 							  size_t datalen,
 							  uintptr_t *out_addr,
 							  uintptr_t *out_result);

 This function takes the newly created hotpatch object, along with a path to the
 shared library in the variable "sofile", the optional function "symbol" to invoke,
 along with the serialized arguments to the function provided in "data" and
 "datalen" which are also optional. The return address of where the library was
 loaded is returned in "out_addr" and the return value of the invocation of
 "symbol" is returned in "out_result". On success this returns 0 and on failure
 returns -1.

 The verbosity levels can be adjusted accordingly from 0 to 6 to see debugging
 information for investigating errors.

 The usefulness of the "data" and "datalen" parameters is extremely high. Suppose
 the user has a custom function they want to invoke, and the arguments of the
 function is a big struct or a class. The user can then write a wrapper function
 that takes a serialized buffer of this struct/class along with the length of the
 buffer and invoke that wrapper function. This wrapper function can then
 deserialize this buffer into the struct/class as needed and call the actual
 function that the user really wanted to invoke. This functionality is only
 available by the API and not by the "hotpatcher" executable.

 - void hotpatch_destroy(hotpatch_t *hp);

 This function cleans up memory and resources used by the hotpatch opaque object.

 Sample Program
 ==============

 #include <hotpatch.h>

 int main(int argc, char **argv)
 {
 	pid_t pid = argc > 1 ? atoi(argv[1]) : 0;
 	hotpatch_t *hp = hotpatch_create(pid, 1);
 	if (hp) {
 		unsigned char *data = (unsigned char *)"my custom serialized data";
 		size_t datalen = strlen((char *)data) + 1;
 		uintptr_t result1, result2;
 		hotpatch_inject_library(hp, "libhotpatchtest.so", "mysym",
 						data, datalen, &result1, &result2);
 		hotpatch_destroy(hp);
 	}
 	return 0;
 }

 Usage: Hotpatcher
 ==================

 The commandline "hotpatcher" can be executed with the "-h" option to see the
 various options that are supported.

 A sample execution of "hotpatcher" into the current running shell can be done as
 below:

 Let's say the library libhotpatchtest.so is in the current directory.

 bash> ./hotpatcher -l ./libhotpatchtest.so -s mysym -v1 $$

 On success the "/tmp/hotpatchtest.log" file can be checked if it has the
 timestamp of the injection.

 Uses of Hotpatch
 =================
 Most uses of hotpatch are related to custom modifications of processes for which
 the users do not have source code available.

 - System administrators can use hotpatch to inject their own custom libraries in
  already running processes and change behavior as per requirement. Some such
 behavior could be adding a library that creates a thread and heartbeats to a
 monitoring system.

 - Many software applications, that are not mission critical, are not built with
  mechanisms to update their software without having to stop the application and
 restarting it. Hotpatch can help modify applications to restart and do other
 fancy tricks without losing the PID and the other states such as file handles of
 the applications that might be very useful or too risky to let go.

 - Users can inject a library and then set up RPC service calls for the target
  application without changing any code.

 - Users can inject a library and with import table modifications can instrument
  the target application for things like profiling, reverse engineering and also
 debugging. This is useful as it does not necessarily need the application to be
 recompiled and performance numbers can be extracted. The code to do import table
 modifications is currently outside the scope of hotpatch.

 - Users can create threads in other processes and make them work like a cluster
  of processes that they control.

 - Users can modify another application and make it perform better by doing
  tricks in the injected code.

 License & Copyright
 ===================

 The license/copyright can be found in the COPYRIGHT document in the source code.

 ==THE END==
	Introduction to Hotpatch
	=========================
	Hotpatch is a library that can be used to dynamically load a shared library
	(.so) file on Linux from one process into another already running process,
	without affecting the execution of the target process. The API is a C API, but
	also supported in C++.

	The current version is 0.2.

	The limitations, directions on how to use, and possible uses of hotpatch will be
	explained in this document.

	The main idea of hotpatch stems from the fact that in Linux, it is not easy to
	load a library into another already running process. In Windows, there is an API
	called CreateRemoteThread() that can load a library into another process very
	easily with a couple of API calls. Hotpatch makes this functionality available
	to Linux users and developers, with a single API call. Unlike other available
	injection libraries, hotpatch restores the execution of the process to its
	original state.

	The user can do the following with hotpatch:
	- load his/her own .so file into an already running process
	- invoke a custom symbol/function in that .so file
	- pass arguments to that function as long as it is serialized to the form of a
	byte buffer and length of the buffer. This shall be explained more later.

	Hotpatch is available as an API with a header file called "hotpatch.h" and a
	.so file called "libhotpatch.so", and also a commandline application called
	"hotpatcher" which can inject .so files into processes via the commandline
	itself. Hotpatch also comes with a test .so called "libhotpatchtest.so"
	which can be used via the commandline "hotpatcher" application to test out
	the working of hotpatch on any system. The "libhotpatchtest.so" has a symbol
	"mysym" that can be invoked, and it writes to the "/tmp/hotpatchtest.log" file
	with the timestamp at which the .so file was injected and anything else.

	Limitations
	============
	NOTE: If hotpatch is compiled in 64-bit mode, it can inject only into 64-bit processes, and if compiled in 32-bit mode it can inject into 32-bit processes only.

	There are some limitations, the main being that the user can inject a library
	.so file only in a process on which the user has privileges over. For example,
	as the root user, hotpatch can inject libraries into any process, but as a
	regular non-root user, hotpatch can inject libraries into only those processes
	that hotpatch has access to, i.e. the user's processes and any other via sudo
	privileges.

	The other limitation is that if the user needs to compile his shared library
	with the linker options "-fPIC -nostartfiles" so that hotpatch can reliably load
	the .so file. If this is not available to the user, then the user needs to explicitly provide the symbol he/she wants to invoke in the target process.

	Another limitation is that injection for a particular .so file can happen only
	once in the target process. Each library that is injected can be injected only
	once into the target process.

	Usage: API
	===========

	The "hotpatch.h" header file needs to be included by the user. There are 3 main
	API calls that matter. Each of them have to be called in the order as shown
	below in the sample program.

	- hotpatch_t *hotpatch_create(pid_t pid, int verbose);

	This function takes a PID of the target process, and the verbosity level
	(between 0 to 6), and returns an opaque object which contains further intimate
	details about the process such as current library mappings, and locations of the
	important functions needed for hotpatch to do its work.

	- int hotpatch_inject_library(hotpatch_t *hp,
	const char *sofile,
	const char *symbol,
	const unsigned char *data,
	size_t datalen,
	uintptr_t *out_addr,
	uintptr_t *out_result);

	This function takes the newly created hotpatch object, along with a path to the
	shared library in the variable "sofile", the optional function "symbol" to invoke,
	along with the serialized arguments to the function provided in "data" and
	"datalen" which are also optional. The return address of where the library was
	loaded is returned in "out_addr" and the return value of the invocation of
	"symbol" is returned in "out_result". On success this returns 0 and on failure
	returns -1.

	The verbosity levels can be adjusted accordingly from 0 to 6 to see debugging
	information for investigating errors.

	The usefulness of the "data" and "datalen" parameters is extremely high. Suppose
	the user has a custom function they want to invoke, and the arguments of the
	function is a big struct or a class. The user can then write a wrapper function
	that takes a serialized buffer of this struct/class along with the length of the
	buffer and invoke that wrapper function. This wrapper function can then
	deserialize this buffer into the struct/class as needed and call the actual
	function that the user really wanted to invoke. This functionality is only
	available by the API and not by the "hotpatcher" executable.

	- void hotpatch_destroy(hotpatch_t *hp);

	This function cleans up memory and resources used by the hotpatch opaque object.

	Sample Program
	==============

	#include <hotpatch.h>

	int main(int argc, char **argv)
	{
	pid_t pid = argc > 1 ? atoi(argv[1]) : 0;
	hotpatch_t *hp = hotpatch_create(pid, 1);
	if (hp) {
	unsigned char data = (unsigned char )"my custom serialized data";
	size_t datalen = strlen((char *)data) + 1;
	uintptr_t result1, result2;
	hotpatch_inject_library(hp, "libhotpatchtest.so", "mysym",
	data, datalen, &result1, &result2);
	hotpatch_destroy(hp);
	}
	return 0;
	}

	Usage: Hotpatcher
	==================

	The commandline "hotpatcher" can be executed with the "-h" option to see the
	various options that are supported.

	A sample execution of "hotpatcher" into the current running shell can be done as
	below:

	Let's say the library libhotpatchtest.so is in the current directory.

	bash> ./hotpatcher -l ./libhotpatchtest.so -s mysym -v1 $$

	On success the "/tmp/hotpatchtest.log" file can be checked if it has the
	timestamp of the injection.

	Uses of Hotpatch
	=================
	Most uses of hotpatch are related to custom modifications of processes for which
	the users do not have source code available.

	- System administrators can use hotpatch to inject their own custom libraries in
	already running processes and change behavior as per requirement. Some such
	behavior could be adding a library that creates a thread and heartbeats to a
	monitoring system.

	- Many software applications, that are not mission critical, are not built with
	mechanisms to update their software without having to stop the application and
	restarting it. Hotpatch can help modify applications to restart and do other
	fancy tricks without losing the PID and the other states such as file handles of
	the applications that might be very useful or too risky to let go.

	- Users can inject a library and then set up RPC service calls for the target
	application without changing any code.

	- Users can inject a library and with import table modifications can instrument
	the target application for things like profiling, reverse engineering and also
	debugging. This is useful as it does not necessarily need the application to be
	recompiled and performance numbers can be extracted. The code to do import table
	modifications is currently outside the scope of hotpatch.

	- Users can create threads in other processes and make them work like a cluster
	of processes that they control.

	- Users can modify another application and make it perform better by doing
	tricks in the injected code.

	License & Copyright
	===================

	The license/copyright can be found in the COPYRIGHT document in the source code.

	==THE END==