ip2unix – Turn IP sockets into Unix domain sockets - JOYK Joy of Geek, Geek News, Link all geek

IP2Unix - Turn IP sockets into Unix domain sockets

Executes a program and converts IP to Unix domain sockets at runtime based on a list of rules, either given via short command line options (see) or via a file containing a list of rules separated via newline. The first matching rule causes ip2unix to replace the current IP socket with a Unix domain socket based on the options given. For example if ais specified, the Unix domain socket will bind or listen to the file given.

Problem statement

A lot of programs are designed to only work with IP sockets, however very few of them allow to communicate via Unix domain sockets. Unix domain sockets usually are just files, so standard Unix file permissions apply to them.

IP sockets also have the disadvantage that other programs on the same host are able to connect to them, unless you use complicated netfilter rules or network namespaces.

So if you either have a multi-user system or just want to separate privileges, Unix domain sockets are a good way to achieve that.

Another very common use case in nowadays systems is when you’re using systemd and want to use socket units for services that don’t support socket activation. Apart from getting rid of the necessity to specify explicit dependencies, this is also very useful for privilege separation, since a lot of services can be run in a separate network namespace.

The systemd use case is also useful even when not using Unix domain sockets in socket units, since it allows to add IP-based socket activation to services that don’t support it.

Short example

Let’s say you have a small HTTP server you want to make available behind a HTTP reverse proxy.

$ ip2unix -r path=/run/my-http-server.socket my-http-server

This will simply convert all IP sockets to the Unix domain socket available at /run/my-http-server.socket . If you use a web server like nginx , you can use the following directive to connect to that socket:

proxy_pass http://unix:/run/my-http-server.socket;

More examples can be found further below in section.

A short summary of all the options is available via ip2unix --help or man ip2unix if you want to see all the details and options available.

1. Build from source

1.1. Requirements

Meson , at least version 0.46.0.
Ninja , at least version 1.5.
yaml-cpp , at least version 0.5.0 Requirement will be removed in ip2unix version 3, since the YAML rule file format is deprecated.
C++ compiler supporting C++17 ( GNU G++ version 7.0 onwards).
Python 3, at least version 3.6 is needed for running the integration tests.

Optional dependencies:

AsciiDoc or Asciidoctor for generating the manpage. The former is recommended as it generates a better manpage and also provides validation.
pytest for running automated tests.
systemd-socket-activate helper to run test cases specific to systemd socket activation support.

1.2. Cloning the repository

The source code can be fetched via Git using the following command:

$ git clone https://github.com/nixcloud/ip2unix.git

You will get an ip2unix directory inside your current working directory. All of the following steps are to be performed inside this ip2unix directory.

1.2.1. Using the Nix package manager

This is the easiest and recommended way to compile it from source and it should work on any distribution.

If you are not running NixOS you can install Nix via the following command:

$ curl https://nixos.org/nix/install | sh

In order to build ip2unix issue the following command from the top of the source tree:

$ nix-build

This takes care of fetching the dependencies, building and running the test suite. The resulting command can now be found in result/bin/ip2unix .

If you want to add the package to your user environment, you can install it using the command:

$ nix-env -f . -i

1.2.2. Debian and derivatives

To install the required dependencies:

$ sudo apt install meson g++ libyaml-cpp-dev pkg-config

If you want to have the manpage:

$ sudo apt install asciidoctor

In case you want to run the test suite, pytest is required:

$ sudo apt install python3-pytest

1.2.3. RPM-based distributions

To install the required dependencies:

$ sudo yum install meson gcc-c++ yaml-cpp-devel

If you want to have the manpage:

$ sudo yum install asciidoctor

If you want to run the test suite:

$ sudo yum install python3-pytest

1.2.4. Arch Linux and derivatives

To install the required dependencies:

$ sudo pacman -S yaml-cpp meson gcc pkg-config

If you want to have the manpage:

$ sudo pacman -S asciidoctor

In case you want to run the test suite:

$ sudo pacman -S python-pytest

1.3. Building

$ meson build

If you want to specify a different compiler executable, eg. g++-7 :

$ CXX=g++-7 meson build

Compile:

$ ninja -C build

The executable is then placed in build/ip2unix , so to show the usage:

$ build/ip2unix --help

1.4. Installation

To install ip2unix , run the following command:

$ ninja -C build install

By default, this will install ip2unix in /usr/local/bin/ip2unix .

1.5. Running tests

$ ninja -C build test

2. Rule specification

Arguments specified via -r contain a comma-separated list of either flags or options. If a value contains a comma ( , ), it has to be escaped using a backslash ( \ ) character. If you want to have a verbatim backslash character just use two consecutive backslashes instead.

The following flags are available:

in | out

Whether this rule applies to a server-side socket ( in ), a client-side socket ( out ) or both if neither in nor out is specified.

tcp | udp

Specifies the IP type, which currently is either tcp for TCP sockets, udp for UDP sockets or if it is not defined it matches both UDP and TCP sockets.

systemd [= FD_NAME ]

Use the socket passed along via file descriptor by systemd instead of creating one.

An optional file descriptor name ( FD_NAME ) can be specified to distinguish between several socket units. This corresponds to the FileDescriptorName systemd socket option.

reject [= ERRNO ]

Reject calls to connect and bind with EACCES by default or the ERRNO specified either via name or as an integer.

blackhole

When binding the socket, use a temporary file system path and unlink it shortly after the bind . This is a way to deactivate a specific socket without the application noticing.

ignore

Prevents a socket from being converted to a Unix domain socket if this is set. This is useful to exempt specific sockets from being matched when another rule matches a broad scope.

These options are available:

addr [ ess ]= ADDRESS

The IP address to match, which can be either an IPv4 or an IPv6 address.

port = PORT [- PORT_END ]

UDP or TCP port number which for outgoing connections specifies the target port and for incomping connections the port that the socket is bound to.

If a range is specified by separating two port numbers via - , the given range is matched instead of just a single port. The range is inclusive, so if 2000-3000 is specified, both port 2000 and port 3000 are matched as well.

path = SOCKET_PATH

The path to the socket file to either bind or connect to.

Placeholders are allowed here and are substituted accordingly:

port number

IP address or unknown

socket type ( tcp , udp or unknown )

verbatim %

3. Examples

3.1. Simple HTTP client/server

The following command spawns a small test web server listening on /tmp/test.socket :

$ ip2unix -r in,path=/tmp/test.socket python3 -m http.server 8000

This connects to the above test server listening on /tmp/test.socket and should show a directory listing:

$ ip2unix -r out,path=/tmp/test.socket curl http://1.2.3.4/

3.2. More complicated example

For example the following could be put into a file given by the -f command line argument:

out,port=53,ignore
out,tcp,path=/run/some.socket
in,addr=1.2.3.4,path=/run/another.socket
in,port=80,address=abcd::1,blackhole
in,port=80,reject=EADDRINUSE
in,tcp,port=22,systemd=ssh

Each line corresponds to a single rule, that is processed in order of appearance and the above example would result in the following:

All outgoing connections to port 53 (no matter if it’s TCP or UDP) will not be converted into Unix domain sockets.
This rule will redirect all TCP connections except to port 53 (see above) to use the Unix domain socket at /run/some.socket .
Matches the socket that listens to any port on the IPv4 address 1.2.3.4 and instead binds it to the Unix domain socket at /run/another.socket .
The application may bind to the IPv6 address abcd::1 on port 80 but it will not receive any connections, because no socket path exists.
Trying to bind to port 80 on addresses other than abcd::1 will result in an EADDRINUSE error.
Will prevent the TCP socket that would listen on port 22 to not listen at all and instead use the systemd-provided file descriptor named ssh for operations like accept (2) .

The same can be achieved solely using -r commandline arguments:

$ ip2unix -r out,port=53,ignore \
          -r out,tcp,path=/run/some.socket \
          -r in,addr=1.2.3.4,path=/run/another.socket \
          -r in,port=80,address=abcd::1,blackhole \
          -r in,port=80,reject=EADDRINUSE \
          -r in,tcp,port=22,systemd=ssh

4. Limitations

The program uses LD_PRELOAD ( ld.so (8) ), so it will only work with programs that are dynamically linked against the C library. Using ip2unix on statically linked executables or on executables that don’t use the socket family functions of the C library (like Go programs) will not work at the moment.
If a client which is already using Unix datagram sockets sends packets via sendto or sendmsg to a socket provided by ip2unix without binding first, ip2unix is not able to identify the peer and will subsequently reject the packet. This is not the case when using ip2unix itself on the the client side and it also does not seem to be very common as the author so far did not find such an application in the wild.

However, if this really is an issue to you, the recommended workaround is either to use ip2unix to wrap the client (if it supports IP sockets) or fix the server to natively use Unix domain sockets.

5. Similar projects

socket_wrapper

The goal is a different one here and its main use is testing. Instead of using rules, socket_wrapper turns all of the IP sockets into Unix sockets and uses a central directory to do the mapping.

Containing all Unix sockets into one directory has the nice effect that it is easy to map any address/port combination to Unix sockets. While this is way easier to implement than our approach it has the drawback that everything is contained and no IP communication is possible anymore.

6. Thanks

Special thanks to the NLnet foundation for sponsoring the initial work on this project.

7. Copyright

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

ip2unix – Turn IP sockets into Unix domain sockets