ip2unix(1)

ifndef::manmanual[] :doctitle: IP2Unix - Turn IP sockets into Unix domain sockets endif::[] :revdate: November 2018 ifndef::manmanual[] :toc: macro :numbered: :toc-title: endif::[]

ifdef::manmanual[] == Name

ip2unix - Turn IP sockets into Unix domain sockets

== Synopsis

:rule_or_file: pass:attributes,quotes[-r 'RULE' | -f 'FILE'] :rulespec: {{rule_or_file}} [{rule_or_file}]...

[verse] ip2unix [-v...] [-p] {rulespec} 'PROGRAM' ['ARGS'...] ip2unix [-v...] [-p] -c {rulespec} ip2unix -h ip2unix --version

endif::[]

ifndef::manmanual[] :man_url: http://man7.org/linux/man-pages :sysdman_url: https://www.freedesktop.org/software/systemd/man

:1: {man_url}/man8/ld.so.8.html#ENVIRONMENT :2: {man_url}/man2/accept.2.html :3: {sysdman_url}/systemd.socket.html :4: pass:attributes,quotes[{3}#FileDescriptorName=] :5: {man_url}/man7/glob.7.html

:xt_owner_url: {man_url}/man8/iptables-extensions.8.html :xt_owner: pass:attributes,quotes[{xt_owner_url}[iptables owner module]] :socat: pass:attributes,quotes[http://www.dest-unreach.org/socat/[socat]]

:LD_PRELOAD: pass:attributes,quotes[LD_PRELOAD ({1}[ld.so(8)])] :syscall_accept: pass:attributes,quotes[{2}[accept(2)]] :systemd_socket: pass:attributes,quotes[{3}[systemd.socket(5)]] :man_glob: pass:attributes,quotes[{5}[glob(7)]] :fdname: pass:attributes,quotes[{4}[FileDescriptorName]] :rulespec: <<rule-specification,Rule specification>> :copy: (C) 2018 aszlig endif::[] ifdef::manmanual[] :LD_PRELOAD: pass:quotes[LD_PRELOAD (see ld.so(8))] :syscall_accept: pass:quotes[accept(2)] :systemd_socket: pass:quotes[systemd.socket(5)] :man_glob: pass:quotes[glob(7)] :fdname: pass:quotes[FileDescriptorName (see systemd.socket(5))] :rulespec: pass:quotes[RULE SPECIFICATION] :copy: (C) 2018 aszlig endif::[]

:lgpl_url: https://www.gnu.org/licenses/lgpl-3.0.html

ifndef::without-systemd[:systemd_comma: ,] ifdef::without-systemd[:systemd_comma:]

ifndef::without-systemd[:systemd_backslash: ] ifdef::without-systemd[:systemd_backslash:]

ifdef::manmanual[] == Description endif::manmanual[]

Executes a program and converts IP to Unix domain sockets at runtime via {LD_PRELOAD} based on a list of rules, either given via short command line options (see {rulespec}) 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 a <<rule-socket-path,path>> is specified, the Unix domain socket will bind or listen to the file given.

ifndef::manmanual[]

[discrete] == 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.

[discrete] == Short example

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

[source,sh-session]

$ 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 https://nginx.org/[nginx], you can use the following directive to connect to that socket:

[source,nginx]

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

More examples can be found further below in section <<examples,Examples>>.

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.

ifndef::manmanual[] [discrete] = Table of Contents

toc::[] endif::[]

== Build from source

See link:INSTALL.adoc[INSTALL.adoc] for information on how to build and/or install ip2unix on your system.

endif::[]

ifdef::manmanual[]

== Options

-c, --check:: This is to validate whether the given rules are 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 specified multiple times to add more rules.

-f, --file='FILE':: Read rules from 'FILE', which contains a newline-separated list of rules as specified via -r. Empty lines as well as lines starting with # are skipped. Whitespace characters at the beginning of each line are stripped as well.

-v, --verbose:: Increases the level of verbosity, according to the following table:

'FATAL' (default);; Only print fatal errors which cause program termination. '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.

endif::[]

== Rule specification

Arguments specified via -r contain a comma-separated list of matches and a single action of what to do when a match is found. 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.

=== Matches The following matches are available:

in | out:: Match either a server-side socket (in), a client-side socket (out) or both if neither in nor out is specified.

tcp | udp | stream | d[ata]gram:: Match the socket type, which currently is either a stream (alias: tcp) or datagram (aliases: dgram or udp).

addr[ess]='ADDRESS':: The IP address to match, which can be either an IPv4 or an IPv6 address.

port='PORT'[-'PORT_END']:: Match the UDP or TCP port number which for outgoing connections specifies the target port and for incoming 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.

[[rule-from-unix]]from-unix='PATTERN':: Use an existing Unix domain socket with a filename matching 'PATTERN'. This is useful for example if a program hardcodes the socket path and you want to change it. + The syntax for 'PATTERN' is similar to {man_glob} and allows the following wildcards: + [horizontal] ?;; Match any single character except / *;; Match zero or more characters except / **;; Match zero or more path components, eg. a/**/z matches a/z, a/b/z, a/b/cde/z, a/b/c/c/d/z and so on […];; Match a single character via a series of either verbatim characters or ranges, eg. [a-cijq-s] matches either a, b, c, i, j, q, r or s [!…];; Same as above, but negates the match \X;; Remove the special meaning of the character 'X', eg. \? literally matches ?

ifndef::without-abstract[] from-abstract='PATTERN':: Similar to <<rule-from-unix,from-unix>> but matches 'PATTERN' against an abstract socket name. endif::[]

=== Actions

[[reject]]reject[='ERRNO']:: Reject calls to connect and bind with EACCES by default or the 'ERRNO' specified either via name or as an integer.

[[blackhole]]blackhole:: Turn the socket into a Unix domain socket but do not make it available for clients to connect. This is useful to deactivate certain sockets without causing errors in the application (unlike <<reject,reject>>). + Technically, this means that we bind to a Unix socket using a temporary file system path and unlink it shortly thereafter.

ignore:: Prevent 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.

[[rule-socket-path]]path='SOCKET_PATH':: Convert the socket into a Unix domain socket at the file specified by 'SOCKET_PATH', which is either created during bind or used as the target when connecting. + Placeholders are allowed here and are substituted accordingly: + [horizontal] %p;; port number or unknown if not an IP socket %a;; IP address or unknown if not an IP socket %t;; socket type (tcp, udp or unknown if it's neither a stream nor datagram socket) %%;; verbatim %

noremove:: If this flag is given in conjunction with a <<