Contents

TCP sockets

TCP sockets provide a flexible and high-performance stream-based transport that is almost universally supported. They come with a few important considerations and caveats which are outlined below.

Platform support

TCP sockets are supported on all platforms.

Default bind interface

Mutagen binds to all interfaces if none is specified in a forwarding endpoint. This behavior mirrors that of programs like SSH.

Example network binding behaviors

  • tcp::8080

    Bind to all interfaces on port 8080.

  • tcp6::8080

    Bind to all IPv6 interfaces on port 8080.

  • tcp:localhost:8080

    Bind to only the loopback interface(s) on port 8080.

  • tcp4:localhost:8080

    Bind to only the IPv4 loopback interface on port 8080.

It’s important to be cognizant of this to avoid accidentally exposing secure internal infrastructure via an exposed port on your local system when working in a public network environment without a firewall (which, for example, macOS doesn’t enable by default).

Privileged ports

Most platforms restrict which users and programs can bind to so-called “privileged ports”. Exactly which ports are privileged and which users/programs are allowed to bind to them varies by operating system, but typically any port less than 1024 (e.g. port 80 or 443) is restricted to superusers or programs with certain permission bits set. The easiest way to work around these restrictions is to simply choose another port outside of this privileged range. For example, port 8080 is commonly used to replace port 80 in development. It’s worth noting that port numbers don’t have to match, so it’s perfectly acceptable to create a forwarding session like the following:

mutagen forward create tcp:localhost:8080 docker://web_container:tcp:localhost:80

It’s also worth noting that these restrictions only affect the source end of the forwarding (i.e. the first endpoint specified to the mutagen forward create command), so there’s no problem forwarding to privileged ports.

For additional information, please see the discussion in Issue #134.

Linux

On Linux, programs can also have permissions set by a superuser that enable them to bind to privileged ports. This is done using the setcap command. This is what allows certain programs (e.g. web servers) to bind to privileged ports without running as a superuser. For example, you can enable privileged ports for the Mutagen daemon using a command like:

sudo setcap setcap 'cap_net_bind_service=+ep' /path/to/mutagen

Note that this will only affect local Mutagen endpoints, not those running inside agents. You should consult the setcap man page before running this command to ensure that you fully understand the implications.