IP2UNIX(1)

IP2Unix Manual

IP2UNIX(1)

NAME¶

ip2unix - Turn IP sockets into Unix domain sockets

SYNOPSIS¶

ip2unix [-v...] [-p] -f RULES_FILE PROGRAM [ARGS...]
ip2unix [-v...] [-p] -F RULES_DATA PROGRAM [ARGS...]
ip2unix [-v...] [-p] -r RULE [-r RULE]... PROGRAM [ARGS...]
ip2unix [-v...] [-p] -c -f RULES_FILE
ip2unix [-v...] [-p] -c -F RULES_DATA
ip2unix [-v...] [-p] -c -r RULE [-r RULE]...
ip2unix -h
ip2unix --version

DESCRIPTION¶

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 RULE SPECIFICATION) or via a file with a list of rules (see RULE FILE FORMAT). 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 a socketPath is specified, the Unix domain socket will bind or listen to the given path.

OPTIONS¶

-c, --check

This is to validate whether the rule file is correct and the program just prints all validation errors to stderr and exits with exit code 0 if validation was successful and 1 if not.

-h, --help

Show command line usage and exit.

--version

Show version information and exit.

-p, --print

Print out the rules that are in effect in a tabular format. If you do not want to run the PROGRAM, you can use the -c option to exit after printing the rules.

-r, --rule=RULE

A single rule for one particular socket to match, can be used several times to specify a set of rules similar to the sequence of the rule file.

-f, --rules-file=RULES_FILE

Specifies a YAML or JSON file consisting of a sequence of rules.

-F, --rules-data=RULES_DATA

Similar to -f, but instead of specifying a file, directly pass the contents as an argument.

-v, --verbose

Increases the level of verbosity, according to the following table:

FATAL (default)

Only prints fatal errors that causes the program to terminate.

ERROR (-v)

Also print errors that are recoverable.

WARNING (-vv)

Also print messages that might indicate possible problems.

INFO (-vvv)

Also print informational messages about ip2unix behavior.

DEBUG (-vvvv)

Also show messages about ip2unix internals along with source information.

TRACE (-vvvvv)

Print every log message possible.

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

Corresponds to the direction rule file option and if it is not set, both incoming and outgoing connections are matched.

tcp | udp

Either match TCP or UDP sockets or both if none of these flags are set (type rule file option).

systemd[=FD_NAME]

Enable systemd socket activation (see socketActivation below), optionally specifying a file descriptior name (fdName).

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

Don’t handle the socket matching this rule, see the corresponding rule file option *ignore.

These options are available:

addr[ess]=ADDRESS

Optional, specifies an IPv4 or IPv6 address, see address rule file option.

port=PORT[-PORT_END]

Optional, specifies a port to match, see the port and optionally the portEnd rule file option if you want to specify a port range.

path=SOCKET_PATH

The path to the socket file to either bind or connect to, which is similar to the socketPath rule file option but also allows relative paths.

RULE FILE FORMAT¶

The rule file (specified via -f is a YAML file (or JSON, as it is a subset of YAML), consisting of an array of objects.

Each object consists of keys/values which define which IP sockets to match and which Unix domain sockets to assign them to.

Rule file options¶

direction

Whether this rule applies to a server-side socket (incoming), a client-side socket (outgoing) or both if not defined.

type

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.

address

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

port

UDP or TCP port number (depending on which type is set), which for outgoing connections specifies the target port and for incomping connections the port that the socket is bound to.

portEnd

Optionally specifies the end of a port range to match, so for example if port is 2000 and portEnd is 3000 all ports in the range from 2000 to 3000 (inclusive) are matched.

socketPath

The path to the socket file to use for either binding or connecting to depending on whether the above options apply for a particular IP socket.

Placeholders are allowed here and those are substituted accordingly:

%p	port number
%a	IP address or unknown
%t	socket type (tcp, udp or unknown)
%%	verbatim %

socketActivation

Whether to use systemd socket activation instead of a socketPath. See systemd.socket(5).

fdName

An optional file descriptor name for socket activation which can be used to distinguish between several socket units. This corresponds to the FileDescriptorName (see systemd.socket(5)) systemd socket option.

reject

If true, reject calls to connect and bind with EACCES.

rejectError

Specifies an alternative error code to be returned by reject instead of EACCES. This can be either a string such as EADDRINUSE (case does not matter) or an integer.

blackhole

If true, a temporary file system path is used and unlinked shortly thereafter, so the socket is effectively deactivated in a way that the application should not recognize. Only valid if direction is incoming.

ignore

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

EXAMPLES¶

Simple HTTP client/server¶

On the server side with the rule file rules-server.yaml:

- direction: incoming


  socketPath: /tmp/test.socket

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

$ ip2unix -f rules-server.yaml python3 -m http.server 8000

The same can be achieved using -r:

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

On the client side with rules-client.yaml:

- direction: outgoing


  socketPath: /tmp/test.socket

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

$ ip2unix -f rules-client.yaml curl http://1.2.3.4/

With the -r option:

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

More complicated example¶

- direction: outgoing                 ## (1)


  port: 53


  ignore: true
- direction: outgoing                 ## (2)


  type: tcp


  socketPath: /run/some.socket
- direction: incoming                 ## (3)


  address: 1.2.3.4


  socketPath: /run/another.socket
- direction: incoming                 ## (4)


  port: 80


  address: abcd::1


  blackhole: true
- direction: incoming                 ## (5)


  port: 80


  reject: true


  rejectError: EADDRINUSE
- direction: incoming                 ## (6)


  type: tcp


  port: 22


  socketActivation: true


  fdName: ssh

1.	All outgoing connections to port 53 (no matter if it’s TCP or UDP) will not be converted into Unix domain sockets.
2.	This rule will redirect all TCP connections except to port 53 (see above) to use the Unix domain socket at /run/some.socket.
3.	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.
4.	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.
5.	Trying to bind to port 80 on addresses other than abcd::1 will result in an EADDRINUSE error.
6.	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,reject=EADDRINUSE \


          -r in,tcp,port=22,systemd=ssh

LIMITATIONS¶

•The program uses LD_PRELOAD (see 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.

ENVIRONMENT VARIABLES¶

IP2UNIX_RULE_FILE

When used in conjunction with LD_PRELOAD (see ld.so(8)), this environment variable has to be set as well, specifying the absolute path to the rule file (see RULE FILE FORMAT above).

AUTHOR¶

Written by aszlig <aszlig@nix.build>

COPYRIGHT¶

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

November 2018

IP2Unix 2.1.4

Main

Development

Information

Community

Social media

Other