Commit 311ea3d1 authored by Dom Sekotill's avatar Dom Sekotill
Browse files

Added 'Running' & 'How it Works' sections to README.md

parent 29833241
Loading
Loading
Loading
Loading
+39 −0
Original line number Diff line number Diff line
@@ -47,3 +47,42 @@ CFLAGS variable when configuring:
The log messages are then appended to the file named at run-time in the 
`RESOLV_NS_OVERRIDE_LOG` environment variable. If the value of 
`RESOLV_NS_OVERRIDE` is '-' the messages are printed to `stderr`.


Running
-------

To use `resolv-ns-override`, several environment variables must be set:

- `LD_PRELOAD`: This must the *absolute* path to the library binary.
                See [How it Works](#how-it-works) for an explaination of what it does.
- `NAMESERVER1`: This must be set to the IPv4 address of the first name server 
                 to use.
- `NAMESERVERx`: Where `x` is an integer between 2 and 9. These are used to set 
                 addresses for any additional name servers.
                 
Any program which uses the system resolver and has been compiled to use shared 
libraries can then be run in this environment and will use the configured name 
servers.

> Note: only programs which use the system resolver (ie. through the `sockets` 
> library) will work with `resolv-ns-override`

> Note: only programs that have been dynamically linked with `glibc`
> (the GNU C library implementation) will work with `resolv-ns-override`. It 
> will not work on systems using μClibc, BSD libc, etc.


How it Works
------------

The library functions are inserted by pre-loading using the `LD_PRELOAD` 
environment variable. This variable is set to an absolute path pointing to a 
library binary.
It prompts the dynamic loader to load the symbols from the library 
before anything else, replacing any functions of the same name (or more 
acurately, occupying the name in the symbol table) from another library.

In this case the function `__res_maybe_init()` (from the glibc resolver 
library) is loaded. This function constructs the array of name servers 
which will be used by the resolver.
 No newline at end of file