XIA Interposition Library

Table of Contents Introduction How Do We Do It? What's Covered? What's Not Covered? Detailed Description Mapping between IPv4 and XIA Usage Running Your Application Examples Captured APIs Redirected to XIA Information Only

Introduction

The XSockets API is useful when writing a new socket application from scratch. It would be nice if it were possible to simply recompile an existing socket application and link to the Xsocket library and have it work over XIA. Unfortunately there are enough differences that this is not as easy as one would like. There are minor issues that can be dealt with via search and replace such as address family and the need to append an X to the socket API calls. The main issue is the difference in addressing. A DAG is very different from an IP address, and XIA has nothing similar to a port. The service is simply part of the DAG. So code that looks up services and directly manipulates the sockaddr structure needs to be changed as well.

Porting a simple application such as netcat can be done in a few hours, but a larger application such as Firefox is a major undertaking. And there is no way to port proprietary applications with no source code. To improve the transition to XIA an interposition library has been created that will let unmodified socket applications work on with XIA.

The interposition library is perpetual beta state as we add new functionality required by applications being tested.

How Do We Do It?

The interposition library is implemented as a shared library (xwrap.so</code).>It is loaded into the process space before any systems libraries and takes ownership of all of the function calls that can be used with sockets. This is accomplished by using the <code>LD_PRELOAD environment variable. Each function in the library inspects the function parameters (usually just the file descriptor) to determine if the call should be redirected to the Xsockets API, or if can be passed through to the default API.

• Any call that specifies the AF_INET is captured and the family is replaced with AF_XIA. The only major downside of this is that we cannot currently support applications that might want to use both IP and XIA at the same time. IPv6 code will work in parallel however. Examples here are the socket and inet_ntop among others.
• All name related calls such as getaddrinfo and gethostbyname are essentially nat'ed internally. A more detailed description follows below.
• Any function that takes a file descriptor is checked to see if the descriptor is associated with an Xsocket. If so, the call is redirected to the appropriate XIA API. If not, it's handled normally.

What's Covered?

• All of the traditional socket APIs such as socket, bind, connect, send, and setsockopt have direct XIA analogs and use a simple remapping.
• Address related APIs such as <cod>getaddrinfo&lt;/code&gt;</cod>, gethostbyname and gethostbyaddr
• poll and select are implemented so that they can be used with Xsockets and file descriptors simultaneously.
• Some non-socket related APIs such as fork are also captured because of how sockets are dealt with under the covers.

What's Not Covered?

• Anything that uses a FILE object is not currently supported. This mainly affects old code like some early versions of ftp. At one point the library tried to handle these functions, but it proved problematic and support has been removed.
• Xsockets currently supports a subset of the available socket options. For the most part, success is returned when setting options and a reasonable default is returned when querying. In a few cases an error is returned. Full support for unhandled is being added as the need is encountered.
• Because there is no comparable socket type in the standard library, applications that use content chunks must use the caching API. However, programs may add caching function calls while leaving the existing socket code alone to be run inside the interposition library.
• XIA doesn't currently have support for dup'ing a socket.
• we are still adding support to deal with issues caused by exec
• Apps that use raw socket will most likely fail as they write the packet headers themselves.

Detailed Description

Mapping between IPv4 and XIA

Usage

Running Your Application

A script (`xwrap`) is provided to simplify launching your application with the interposition library. It sets the appropriate environment variables and then launches the application with the `xwrap.so` injected and loaded before the standard libraries. `xwrap` can be found in the `xia-core/bin/` directory.

xwrap myapp myapp_arguments

`xwrap` provides several command line switches for generating log messages that can be useful when porting your application.

xwrap [-tixwv] [-o] cmd -t log a message when entering every wrapped API call -i log informative messages -x log XIA related messages -w log warnings and errors -v log everything (same as -tixw) -o <logfile></logfile> log to the specified file instead of stderr

• The `-t` switch is useful when first looking at an applicaiton to see what function calls are used. However messages are logged whether the API is called with a socket or a file in cases such as the `write` API.
• The `-i` switch causes the wrapper to log informative and debug messages. These are generally more useful for the development of the wrapper than applicaitons using it.
• The `-x` switch logs a message whenever an API call is redirected to the Xsocket API. In some instances, it will also log a message when the XIA API isn't used. This switch can be quite useful for debugging problems.
• The `-w` switch logs warnings and errors. Error messages will be logged from API calls such as `gethostbyname` that are not supported by the interposition library. It will also log error messages in cases such as having the incorrect size for the sockaddr structure.

Examples

Captured APIs

Redirected to XIA

• accept
• accept4
• bind
• close
• connect
• fcntl
• fork
• freeaddrinfo
• freeifaddrs
• gai_strerror
• getaddrinfo
• gethostbyaddr
• gethostbyaddr_r
• gethostbyname
• gethostbyname2
• gethostbyname_r
• gethostbyname2_r
• getifaddrs
• getpeername
• getsockname
• getsockopt
• listen
• poll
• read
• readv
• recv
• recvfrom
• recvmsg
• select
• send
• sendmsg
• sendto
• setsockopt
• shutdown
• socket
• socketpair
• write
• writev

Information Only

The functions below are not either not supported by XIA, or don't provide enough information in their parameters to allow them to be mapped to a corresponding XIA function. However they have been wrapped so that log messages can be generated to indicate that porting issues may be present.

• getnameinfo
• getservbyname
• getservbyname_r
• getservbyport
• getservbyport_r
• execve
• clone