Help:Socket Enhancer

Socket Enhancer is mainly configured using the $SOCKET_ENHANCER_CONFIG environment variable. The syntax for this environment variable is:

SOCKET_ENHANCER_CONFIG=aaaa=bbbbbbb[,cccc=ddddddd][,eeee=fffffff]...

The valid directives are:

  • ipv4=IPV4_ADDRESS - This option specifies the local IPv4 address to use for outbound IPv4 connections for all other destinations (if not otherwise overridden), including outbound IPv6 connections to IPv4-mapped-IPv6 addresses (in that case, it is translated into the appropriate IPv4-mapped-IPv6 equivalent).
  • ipv6=IPV6_ADDRESS - This option specifies the local IPv6 address to use for outbound IPv6 connections for all other destinations (if not otherwise overridden), except those to IPv4-mapped-IPv6 addresses.
  • v4lb=IPV4_ADDRESS - This option specifies the local IPv4 address to use for connections to the IPv4 localhost (127.0.0.0/8)
  • v6ll=IPV6_ADDRESS - This option specifies the local IPv6 address to use for outbound IPv6 connections to link-local destinations (fe80::/10). If a scope ID is present in this parameter, then the application does not need to use a scope ID for such connections. See below for an additional syntax for this parameter.
  • v4m6=IPV6_ADDRESS - This option specifies the local IPv6 address to use for outbound IPv6 connections to IPv4-mapped-IPv6 addresses (::ffff:0:0/96). Usually, the argument to this option will also be an IPv4-mapped-IPv6 address. It is usually not necessary if ipv4= is specified.
  • v6ul=NUMBER - Enable "universal link-local address" mode. When this option is enabled, outbound IPv6 connections, as well as local IPv6 bindings, which specify an address in the fe90::/32 range without an explicit scope ID will be aliased into fe80::/64, where bits 32-63 (starting from the most significant bit) of the original address are used to specify the scope ID (numeric) of the resulting address. See below for the format of the NUMBER value.
  • v6uq=IPV6_ADDRESS - This option specifies the local IPv6 address to use for outbound IPv6 connections to unique local addresses (fc00::/7).
  • freb=NUMBER - Set the IP_FREEBIND socket option before every call to bind() and/or before the bind() in the intercepted connect().

The value for NUMBER in v6ul= and freb= can be 0, 1, 2, or 3:

  • 0: Disable the option (default)
  • 1: Enable for bind().
  • 2: Enable for connect() (for freb= this option applies to the bind() just before the connect()).
  • 3: Enable for both bind() and connect().

The argument to IPv4 addresses must be a dotted-quad IPv4 address with exactly three periods, and decimal numbers from 0 to 255 inclusive between them.

The argument to IPv6 addresses must be a valid IPv6 address according to RFC 4291 section 2.2. Optionally, it may have a %scope_id at the end, which may be a number or interface name.

scope_id is usually only accepted for a link-local address argument. However, as an exception, v6ll= may use the syntax ::%scope_id, which, instead of doing the usual bind() before the connect(), will append the specified scope ID for outbound IPv6 connections to link-local addresses that don't already have a scope ID.

If any IP address or number is invalid, then this will result in an error.

Examples

LD_PRELOAD=/path/to/socket-enhancer SOCKET_ENHANCER_CONFIG=v6ll=::%enp1s0 firefox -no-remote

The above command will launch a new instance of Mozilla Firefox. The browser will be as usual, except that you can also specify link-local addresses in the URL bar (including DNS names that resolve to link-local addresses) without a scope ID, and connections to those link-local addresses will use enp1s0 as the outbound interface.

If the above command does not work, replace enp1s0 with the actual numeric interface ID, as seen in ip addr show:

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    inet 127.0.0.1/8 scope host lo
       valid_lft forever preferred_lft forever
    inet6 ::1/128 scope host 
       valid_lft forever preferred_lft forever
2: enp1s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP group default qlen 1000
    link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff
    inet 10.x.x.x/22 brd 10.x.x.x scope global dynamic enp1s0
       valid_lft 25702sec preferred_lft 25702sec
    inet6 fdxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx/64 scope global temporary dynamic 
       valid_lft 143590sec preferred_lft 3318sec
3: wlp4s0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN group default qlen 1000
    link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff

So for the example above, use ::%2 for enp1s0 and ::%3 for wlp4s0.

This end-user documentation is part of Socket Enhancer. Reproduction and use of this material for any purpose is permitted, provided that a link to this page is provided as attribution.