Network forwarding

Mutagen supports flexible network forwarding, allowing you to connect to services and access applications running on remote systems. It can be particularly useful when developing applications inside containers that you want to access locally. For example, you might want to develop a web application (potentially with multiple backing services) in a containerized environment and access it from your browser. Network forwarding can also be used to reverse tunnel traffic or forward Unix domain sockets, amongst other things.

Design and architecture

Mutagen’s forwarding sessions each operate between an arbitrary pair of endpoints, termed source and destination, forwarding source’s incoming connections to destination. As with synchronization sessions, remote data is transferred over an agent command’s input/output stream, multiplexed in this case to support multiple connection streams, avoiding the need to expose ports publicly.

Endpoint URLs

Forwarding endpoint URLs are similar to synchronization endpoint URLs, except that, instead of naming a filesystem location, they name a network endpoint. The exact format for forwarding endpoint URLs is transport-dependent, but each contains a <network-endpoint> component which has the following format:

<protocol>:<address>

This network endpoint is analagous to the path component of a synchronization URL. For source endpoints, the network endpoint is a listener address on which the endpoint will attempt to bind. For destination endpoints, the network endpoint is a target address that the endpoint will attempt to dial.

The <protocol> and <address> components allow the same values as the network and address arguments (respectively) of Go’s net.Dial and net.Listen functions, except that <protocol> is restricted to tcp, tcp4, tcp6, and unix. On Windows endpoints, an additional npipe protocol is supported for dialing and listening on Windows named pipes.

In the case of Unix domain sockets, the address component is a socket path, which can be either relative or absolute. If a relative path is specified, then it will be resolved relative in a manner dependent on the transport being used.

In the case of Windows named pipes, the address component is a Windows named pipe path, for example \\.\pipe\<pipe-name>. If you’re targeting such a pipe from a POSIX system, then you’ll likely need to escape backslashes in your shell.

Example network endpoints

tcp::8080
Bind to all interfaces on port 8080.
tcp4:localhost:8080
Bind to or target the IPv4 loopback interface on port 8080.
tcp6:localhost:8080
Bind to or target the IPv6 loopback interface on port 8080.
tcp:10.0.1.25:6060
Bind to or target 10.0.1.25 on port 6060.
tcp:example.org:6060
Target example.org on port 6060.
unix:/path/to/socket.sock
Bind to or target a Unix domain socket using an absolute path.
unix:path/to/socket.sock
Bind to or target a Unix domain socket using a relative path. Path resolution for relative paths is transport-dependent.
unix:~/path/to/socket.sock
Bind to or target a Unix domain socket relative to the user's home directory.
npipe:\\.\pipe\somepipename
Bind to or target a Windows named pipe. The endpoint must reside on a Windows system, though it can be targeted from a non-Windows system.

Configuration

Network forwarding configuration is currently minimal, with configuration options controlling:

Session management

Forwarding sessions are managed using the mutagen forward commands, namely create, list, monitor, pause, resume, and terminate. Example usage for these commands can be found in the Getting started guide. The create command comes with a number of flags that control the configuration of the sessions that it creates, and the other forwarding session management commands all include flags that control their behavior. For more information about a particular command, use:

# Show help about a particular forwarding session management command.
mutagen forward <command> --help