feat(torsf): collect tor logs, select rendezvous method, count bytes (#683)

This diff contains significant improvements over the previous
implementation of the torsf experiment.

We add support for configuring different rendezvous methods after
the convo at https://github.com/ooni/probe/issues/2004. In doing
that, I've tried to use a terminology that is consistent with the
names being actually used by tor developers.

In terms of what to do next, this diff basically instruments
torsf to always rendezvous using domain fronting. Yet, it's also
possible to change the rendezvous method from the command line,
when using miniooni, which allows to experiment a bit more. In the
same vein, by default we use a persistent tor datadir, but it's
also possible to use a temporary datadir using the cmdline.

Here's how a generic invocation of `torsf` looks like:

```bash
./miniooni -O DisablePersistentDatadir=true \
           -O RendezvousMethod=amp \
           -O DisableProgress=true \
           torsf
```

(The default is `DisablePersistentDatadir=false` and
`RendezvousMethod=domain_fronting`.)

With this implementation, we can start measuring whether snowflake
and tor together can boostrap, which seems the most important thing
to focus on at the beginning. Understanding why the bootstrap most
often does not converge with a temporary datadir on Android devices
remains instead an open problem for now. (I'll also update the
relevant issues or create new issues after commit this.)

We also address some methodology improvements that were proposed
in https://github.com/ooni/probe/issues/1686. Namely:

1. we record the tor version;

2. we include the bootstrap percentage by reading the logs;

3. we set the anomaly key correctly;

4. we measure the bytes send and received (by `tor` not by `snowflake`, since
doing it for snowflake seems more complex at this stage).

What remains to be done is the possibility of including Snowflake
events into the measurement, which is not possible until the new
improvements at common/event in snowflake.git are included into a
tagged version of snowflake itself. (I'll make sure to mention
this aspect to @cohosh in https://github.com/ooni/probe/issues/2004.)

internal/tunnel/config.go

@@ -2,6 +2,7 @@ package tunnel
 
 import (
 	"context"
+	"errors"
 	"net"
 	"os"
 
@@ -66,6 +67,9 @@ type Config struct {
 	// testTorStart allows us to mock tor.Start.
 	testTorStart func(ctx context.Context, conf *tor.StartConf) (*tor.Tor, error)
 
+	// testTorProtocolInfo allows us to mock getting protocol info.
+	testTorProtocolInfo func(tor *tor.Tor) (*control.ProtocolInfo, error)
+
 	// testTorEnableNetwork allows us to fake a failure when
 	// telling to the tor daemon to enable the network.
 	testTorEnableNetwork func(ctx context.Context, tor *tor.Tor, wait bool) error
@@ -163,6 +167,21 @@ func (c *Config) torStart(ctx context.Context, conf *tor.StartConf) (*tor.Tor, e
 	return tor.Start(ctx, conf)
 }
 
+// errNoTorControl indicate you passed us a tor with a nil control field.
+var errNoTorControl = errors.New("tunnel: no tor control")
+
+// torProtocolInfo calls either testTorProtocolInfo or the
+// proper function to get back protocol information.
+func (c *Config) torProtocolInfo(tor *tor.Tor) (*control.ProtocolInfo, error) {
+	if c.testTorProtocolInfo != nil {
+		return c.testTorProtocolInfo(tor)
+	}
+	if tor.Control == nil {
+		return nil, errNoTorControl
+	}
+	return tor.Control.ProtocolInfo()
+}
+
 // torEnableNetwork calls either testTorEnableNetwork or tor.EnableNetwork.
 func (c *Config) torEnableNetwork(ctx context.Context, tor *tor.Tor, wait bool) error {
 	if c.testTorEnableNetwork != nil {

internal/tunnel/config_test.go

@@ -6,6 +6,7 @@ import (
 	"testing"
 
 	"github.com/apex/log"
+	"github.com/cretz/bine/tor"
 	"github.com/ooni/probe-cli/v3/internal/model"
 )
 
@@ -108,3 +109,16 @@ func TestConfigTorBinary(t *testing.T) {
 		verifyExpectations(t, config, expected, nil)
 	})
 }
+
+func TestConfigTorProtocolInfo(t *testing.T) {
+	t.Run("with nil Control field", func(t *testing.T) {
+		config := &Config{}
+		protocolInfo, err := config.torProtocolInfo(&tor.Tor{})
+		if !errors.Is(err, errNoTorControl) {
+			t.Fatal("unexpected error", err)
+		}
+		if protocolInfo != nil {
+			t.Fatal("expected nil protocol info")
+		}
+	})
+}

internal/tunnel/fake.go

@@ -39,7 +39,7 @@ func (t *fakeTunnel) SOCKS5ProxyURL() *url.URL {
 }
 
 // fakeStart starts the fake tunnel.
-func fakeStart(ctx context.Context, config *Config) (Tunnel, error) {
+func fakeStart(ctx context.Context, config *Config) (Tunnel, DebugInfo, error) {
 	// do the same things other tunnels do:
 	//
 	// 1. abort if context is cancelled
@@ -50,25 +50,30 @@ func fakeStart(ctx context.Context, config *Config) (Tunnel, error) {
 	//
 	// after that, it's all fake and we just create a simple
 	// socks5 server that we can use
+	debugInfo := DebugInfo{
+		LogFilePath: "",
+		Name:        "fake",
+		Version:     "",
+	}
 	select {
 	case <-ctx.Done():
-		return nil, ctx.Err() // simplifies unit testing this code
+		return nil, debugInfo, ctx.Err() // simplifies unit testing this code
 	default:
 	}
 	if config.TunnelDir == "" {
-		return nil, ErrEmptyTunnelDir
+		return nil, debugInfo, ErrEmptyTunnelDir
 	}
 	if err := config.mkdirAll(config.TunnelDir, 0700); err != nil {
-		return nil, err
+		return nil, debugInfo, err
 	}
 	server, err := config.socks5New(&socks5.Config{})
 	if err != nil {
-		return nil, err
+		return nil, debugInfo, err
 	}
 	start := time.Now()
 	listener, err := config.netListen("tcp", "127.0.0.1:0")
 	if err != nil {
-		return nil, err
+		return nil, debugInfo, err
 	}
 	bootstrapTime := time.Since(start)
 	go server.Serve(listener)
@@ -76,5 +81,5 @@ func fakeStart(ctx context.Context, config *Config) (Tunnel, error) {
 		addr:          listener.Addr(),
 		bootstrapTime: bootstrapTime,
 		listener:      listener,
-	}, nil
+	}, debugInfo, nil
 }

internal/tunnel/fake_integration_test.go

@@ -26,7 +26,7 @@ func TestFakeStartStop(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	tunnel, err := tunnel.Start(context.Background(), &tunnel.Config{
+	tunnel, _, err := tunnel.Start(context.Background(), &tunnel.Config{
 		Name:      "fake",
 		Session:   sess,
 		TunnelDir: tunnelDir,

internal/tunnel/fake_test.go

@@ -14,7 +14,7 @@ func TestFakeWithCancelledContext(t *testing.T) {
 	ctx, cancel := context.WithCancel(context.Background())
 	cancel() // immediately fail
 	sess := &MockableSession{}
-	tunnel, err := fakeStart(ctx, &Config{
+	tunnel, _, err := fakeStart(ctx, &Config{
 		Session:   sess,
 		TunnelDir: "testdata",
 	})
@@ -29,7 +29,7 @@ func TestFakeWithCancelledContext(t *testing.T) {
 func TestFakeWithEmptyTunnelDir(t *testing.T) {
 	ctx := context.Background()
 	sess := &MockableSession{}
-	tunnel, err := fakeStart(ctx, &Config{
+	tunnel, _, err := fakeStart(ctx, &Config{
 		Session:   sess,
 		TunnelDir: "",
 	})
@@ -45,7 +45,7 @@ func TestFakeWithFailingMkdirAll(t *testing.T) {
 	expected := errors.New("mocked error")
 	ctx := context.Background()
 	sess := &MockableSession{}
-	tunnel, err := fakeStart(ctx, &Config{
+	tunnel, _, err := fakeStart(ctx, &Config{
 		Session:   sess,
 		TunnelDir: "testdata",
 		testMkdirAll: func(dir string, mode os.FileMode) error {
@@ -64,7 +64,7 @@ func TestFakeSocks5NewFails(t *testing.T) {
 	expected := errors.New("mocked error")
 	ctx := context.Background()
 	sess := &MockableSession{}
-	tunnel, err := fakeStart(ctx, &Config{
+	tunnel, _, err := fakeStart(ctx, &Config{
 		Session:   sess,
 		TunnelDir: "testdata",
 		testSocks5New: func(conf *socks5.Config) (*socks5.Server, error) {
@@ -83,7 +83,7 @@ func TestFakeNetListenFails(t *testing.T) {
 	expected := errors.New("mocked error")
 	ctx := context.Background()
 	sess := &MockableSession{}
-	tunnel, err := fakeStart(ctx, &Config{
+	tunnel, _, err := fakeStart(ctx, &Config{
 		Session:   sess,
 		TunnelDir: "testdata",
 		testNetListen: func(network, address string) (net.Listener, error) {

internal/tunnel/mocks/mocks.go

@@ -0,0 +1,37 @@
+// Package mocks contains mocks for tunnel.
+package mocks
+
+import (
+	"net/url"
+	"time"
+
+	"github.com/ooni/probe-cli/v3/internal/tunnel"
+)
+
+// Tunnel allows mocking a tunnel.
+type Tunnel struct {
+	// MockBootstrapTime allows to mock BootstrapTime.
+	MockBootstrapTime func() time.Duration
+
+	// MockSOCKS5ProxyURL allows to mock Socks5ProxyURL.
+	MockSOCKS5ProxyURL func() *url.URL
+
+	// MockStop allows to mock Stop.
+	MockStop func()
+}
+
+func (t *Tunnel) BootstrapTime() time.Duration {
+	return t.MockBootstrapTime()
+}
+
+// SOCKS5ProxyURL implements Tunnel.SOCKS5ProxyURL.
+func (t *Tunnel) SOCKS5ProxyURL() *url.URL {
+	return t.MockSOCKS5ProxyURL()
+}
+
+// Stop implements Tunnel.Stop.
+func (t *Tunnel) Stop() {
+	t.MockStop()
+}
+
+var _ tunnel.Tunnel = &Tunnel{}

internal/tunnel/mocks/mocks_test.go

@@ -0,0 +1,60 @@
+package mocks
+
+import (
+	"net/url"
+	"testing"
+	"time"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/ooni/probe-cli/v3/internal/atomicx"
+)
+
+func TestTunnel(t *testing.T) {
+	t.Run("BootstrapTime", func(t *testing.T) {
+		var expected time.Duration = 114
+		tun := &Tunnel{
+			MockBootstrapTime: func() time.Duration {
+				return expected
+			},
+		}
+		if tun.BootstrapTime() != expected {
+			t.Fatal("invalid BootstrapTime")
+		}
+	})
+
+	t.Run("SOCKS5ProxyURL", func(t *testing.T) {
+		expected := &url.URL{
+			Scheme:      "https",
+			Opaque:      "",
+			User:        &url.Userinfo{},
+			Host:        "www.google.com",
+			Path:        "/robots.txt",
+			RawPath:     "",
+			ForceQuery:  false,
+			RawQuery:    "",
+			Fragment:    "",
+			RawFragment: "",
+		}
+		tun := &Tunnel{
+			MockSOCKS5ProxyURL: func() *url.URL {
+				return expected
+			},
+		}
+		if diff := cmp.Diff(expected.String(), tun.SOCKS5ProxyURL().String()); diff != "" {
+			t.Fatal(diff)
+		}
+	})
+
+	t.Run("Stop", func(t *testing.T) {
+		called := &atomicx.Int64{}
+		tun := &Tunnel{
+			MockStop: func() {
+				called.Add(1)
+			},
+		}
+		tun.Stop()
+		if called.Load() != 1 {
+			t.Fatal("not called")
+		}
+	})
+}

internal/tunnel/psiphon.go

@@ -30,30 +30,38 @@ func psiphonMakeWorkingDir(config *Config) (string, error) {
 }
 
 // psiphonStart starts the psiphon tunnel.
-func psiphonStart(ctx context.Context, config *Config) (Tunnel, error) {
+func psiphonStart(ctx context.Context, config *Config) (Tunnel, DebugInfo, error) {
+	debugInfo := DebugInfo{
+		LogFilePath: "",
+		Name:        "psiphon",
+		Version:     "",
+	}
 	select {
 	case <-ctx.Done():
-		return nil, ctx.Err() // simplifies unit testing this code
+		return nil, debugInfo, ctx.Err() // simplifies unit testing this code
 	default:
 	}
 	if config.TunnelDir == "" {
-		return nil, ErrEmptyTunnelDir
+		return nil, debugInfo, ErrEmptyTunnelDir
 	}
 	configJSON, err := config.Session.FetchPsiphonConfig(ctx)
 	if err != nil {
-		return nil, err
+		return nil, debugInfo, err
 	}
 	workdir, err := psiphonMakeWorkingDir(config)
 	if err != nil {
-		return nil, err
+		return nil, debugInfo, err
 	}
 	start := time.Now()
 	tunnel, err := config.startPsiphon(ctx, configJSON, workdir)
 	if err != nil {
-		return nil, err
+		return nil, debugInfo, err
 	}
 	stop := time.Now()
-	return &psiphonTunnel{tunnel: tunnel, bootstrapTime: stop.Sub(start)}, nil
+	return &psiphonTunnel{
+		tunnel:        tunnel,
+		bootstrapTime: stop.Sub(start),
+	}, debugInfo, nil
 }
 
 // Stop is an idempotent method that shuts down the tunnel

internal/tunnel/psiphon_integration_test.go

@@ -28,7 +28,7 @@ func TestPsiphonStartStop(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	tunnel, err := tunnel.Start(context.Background(), &tunnel.Config{
+	tunnel, _, err := tunnel.Start(context.Background(), &tunnel.Config{
 		Name:      "psiphon",
 		Session:   sess,
 		TunnelDir: tunnelDir,

internal/tunnel/psiphon_test.go

@@ -13,7 +13,7 @@ func TestPsiphonWithCancelledContext(t *testing.T) {
 	ctx, cancel := context.WithCancel(context.Background())
 	cancel() // immediately fail
 	sess := &MockableSession{}
-	tunnel, err := psiphonStart(ctx, &Config{
+	tunnel, _, err := psiphonStart(ctx, &Config{
 		Session:   sess,
 		TunnelDir: "testdata",
 	})
@@ -28,7 +28,7 @@ func TestPsiphonWithCancelledContext(t *testing.T) {
 func TestPsiphonWithEmptyTunnelDir(t *testing.T) {
 	ctx := context.Background()
 	sess := &MockableSession{}
-	tunnel, err := psiphonStart(ctx, &Config{
+	tunnel, _, err := psiphonStart(ctx, &Config{
 		Session:   sess,
 		TunnelDir: "",
 	})
@@ -45,7 +45,7 @@ func TestPsiphonFetchPsiphonConfigFailure(t *testing.T) {
 	sess := &MockableSession{
 		Err: expected,
 	}
-	tunnel, err := psiphonStart(context.Background(), &Config{
+	tunnel, _, err := psiphonStart(context.Background(), &Config{
 		Session:   sess,
 		TunnelDir: "testdata",
 	})
@@ -62,7 +62,7 @@ func TestPsiphonMkdirAllFailure(t *testing.T) {
 	sess := &MockableSession{
 		Result: []byte(`{}`),
 	}
-	tunnel, err := psiphonStart(context.Background(), &Config{
+	tunnel, _, err := psiphonStart(context.Background(), &Config{
 		Session:   sess,
 		TunnelDir: "testdata",
 		testMkdirAll: func(path string, perm os.FileMode) error {
@@ -82,7 +82,7 @@ func TestPsiphonStartFailure(t *testing.T) {
 	sess := &MockableSession{
 		Result: []byte(`{}`),
 	}
-	tunnel, err := psiphonStart(context.Background(), &Config{
+	tunnel, _, err := psiphonStart(context.Background(), &Config{
 		Session:   sess,
 		TunnelDir: "testdata",
 		testStartPsiphon: func(ctx context.Context, config []byte,

internal/tunnel/tor.go

@@ -55,17 +55,23 @@ var ErrTorReturnedUnsupportedProxy = errors.New(
 	"tor returned unsupported proxy")
 
 // torStart starts the tor tunnel.
-func torStart(ctx context.Context, config *Config) (Tunnel, error) {
+func torStart(ctx context.Context, config *Config) (Tunnel, DebugInfo, error) {
+	debugInfo := DebugInfo{
+		LogFilePath: "",
+		Name:        "tor",
+		Version:     "",
+	}
 	select {
 	case <-ctx.Done():
-		return nil, ctx.Err() // allows to write unit tests using this code
+		return nil, debugInfo, ctx.Err() // allows to write unit tests using this code
 	default:
 	}
 	if config.TunnelDir == "" {
-		return nil, ErrEmptyTunnelDir
+		return nil, debugInfo, ErrEmptyTunnelDir
 	}
 	stateDir := filepath.Join(config.TunnelDir, "tor")
 	logfile := filepath.Join(stateDir, "tor.log")
+	debugInfo.LogFilePath = logfile
 	maybeCleanupTunnelDir(stateDir, logfile)
 	extraArgs := append([]string{}, config.TorArgs...)
 	extraArgs = append(extraArgs, "Log")
@@ -74,39 +80,44 @@ func torStart(ctx context.Context, config *Config) (Tunnel, error) {
 	extraArgs = append(extraArgs, fmt.Sprintf(`notice file %s`, logfile))
 	torStartConf, err := getTorStartConf(config, stateDir, extraArgs)
 	if err != nil {
-		return nil, err
+		return nil, debugInfo, err
 	}
 	instance, err := config.torStart(ctx, torStartConf)
 	if err != nil {
-		return nil, err
+		return nil, debugInfo, err
 	}
+	protoInfo, err := config.torProtocolInfo(instance)
+	if err != nil {
+		return nil, debugInfo, err
+	}
+	debugInfo.Version = protoInfo.TorVersion
 	instance.StopProcessOnClose = true
 	start := time.Now()
 	if err := config.torEnableNetwork(ctx, instance, true); err != nil {
 		instance.Close()
-		return nil, err
+		return nil, debugInfo, err
 	}
 	stop := time.Now()
 	// Adapted from <https://git.io/Jfc7N>
 	info, err := config.torGetInfo(instance.Control, "net/listeners/socks")
 	if err != nil {
 		instance.Close()
-		return nil, err
+		return nil, debugInfo, err
 	}
 	if len(info) != 1 || info[0].Key != "net/listeners/socks" {
 		instance.Close()
-		return nil, ErrTorUnableToGetSOCKSProxyAddress
+		return nil, debugInfo, ErrTorUnableToGetSOCKSProxyAddress
 	}
 	proxyAddress := info[0].Val
 	if strings.HasPrefix(proxyAddress, "unix:") {
 		instance.Close()
-		return nil, ErrTorReturnedUnsupportedProxy
+		return nil, debugInfo, ErrTorReturnedUnsupportedProxy
 	}
 	return &torTunnel{
 		bootstrapTime: stop.Sub(start),
 		instance:      instance,
 		proxy:         &url.URL{Scheme: "socks5", Host: proxyAddress},
-	}, nil
+	}, debugInfo, nil
 }
 
 // maybeCleanupTunnelDir removes stale files inside

internal/tunnel/tor_integration_test.go

@@ -33,7 +33,7 @@ func TestTorStartStop(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	tunnel, err := tunnel.Start(context.Background(), &tunnel.Config{
+	tunnel, _, err := tunnel.Start(context.Background(), &tunnel.Config{
 		Name:      "tor",
 		Session:   sess,
 		TorBinary: torBinaryPath,

internal/tunnel/tor_test.go

@@ -50,7 +50,7 @@ func TestTorTunnelNonNil(t *testing.T) {
 func TestTorWithCancelledContext(t *testing.T) {
 	ctx, cancel := context.WithCancel(context.Background())
 	cancel() // fail immediately
-	tun, err := torStart(ctx, &Config{
+	tun, _, err := torStart(ctx, &Config{
 		Session:   &MockableSession{},
 		TunnelDir: "testdata",
 	})
@@ -64,7 +64,7 @@ func TestTorWithCancelledContext(t *testing.T) {
 
 func TestTorWithEmptyTunnelDir(t *testing.T) {
 	ctx := context.Background()
-	tun, err := torStart(ctx, &Config{
+	tun, _, err := torStart(ctx, &Config{
 		Session:   &MockableSession{},
 		TunnelDir: "",
 	})
@@ -78,7 +78,7 @@ func TestTorWithEmptyTunnelDir(t *testing.T) {
 
 func TestTorBinaryNotFoundFailure(t *testing.T) {
 	ctx := context.Background()
-	tun, err := torStart(ctx, &Config{
+	tun, _, err := torStart(ctx, &Config{
 		Session:   &MockableSession{},
 		TorBinary: "/nonexistent/directory/tor",
 		TunnelDir: "testdata",
@@ -94,7 +94,7 @@ func TestTorBinaryNotFoundFailure(t *testing.T) {
 func TestTorStartFailure(t *testing.T) {
 	expected := errors.New("mocked error")
 	ctx := context.Background()
-	tun, err := torStart(ctx, &Config{
+	tun, _, err := torStart(ctx, &Config{
 		Session:   &MockableSession{},
 		TunnelDir: "testdata",
 		testExecabsLookPath: func(name string) (string, error) {
@@ -112,10 +112,10 @@ func TestTorStartFailure(t *testing.T) {
 	}
 }
 
-func TestTorEnableNetworkFailure(t *testing.T) {
+func TestTorGetProtocolInfoFailure(t *testing.T) {
 	expected := errors.New("mocked error")
 	ctx := context.Background()
-	tun, err := torStart(ctx, &Config{
+	tun, _, err := torStart(ctx, &Config{
 		Session:   &MockableSession{},
 		TunnelDir: "testdata",
 		testExecabsLookPath: func(name string) (string, error) {
@@ -124,6 +124,33 @@ func TestTorEnableNetworkFailure(t *testing.T) {
 		testTorStart: func(ctx context.Context, conf *tor.StartConf) (*tor.Tor, error) {
 			return &tor.Tor{}, nil
 		},
+		testTorProtocolInfo: func(tor *tor.Tor) (*control.ProtocolInfo, error) {
+			return nil, expected
+		},
+	})
+	if !errors.Is(err, expected) {
+		t.Fatal("not the error we expected")
+	}
+	if tun != nil {
+		t.Fatal("expected nil tunnel here")
+	}
+}
+
+func TestTorEnableNetworkFailure(t *testing.T) {
+	expected := errors.New("mocked error")
+	ctx := context.Background()
+	tun, _, err := torStart(ctx, &Config{
+		Session:   &MockableSession{},
+		TunnelDir: "testdata",
+		testExecabsLookPath: func(name string) (string, error) {
+			return "/usr/local/bin/tor", nil
+		},
+		testTorStart: func(ctx context.Context, conf *tor.StartConf) (*tor.Tor, error) {
+			return &tor.Tor{}, nil
+		},
+		testTorProtocolInfo: func(tor *tor.Tor) (*control.ProtocolInfo, error) {
+			return &control.ProtocolInfo{}, nil
+		},
 		testTorEnableNetwork: func(ctx context.Context, tor *tor.Tor, wait bool) error {
 			return expected
 		},
@@ -139,7 +166,7 @@ func TestTorEnableNetworkFailure(t *testing.T) {
 func TestTorGetInfoFailure(t *testing.T) {
 	expected := errors.New("mocked error")
 	ctx := context.Background()
-	tun, err := torStart(ctx, &Config{
+	tun, _, err := torStart(ctx, &Config{
 		Session:   &MockableSession{},
 		TunnelDir: "testdata",
 		testExecabsLookPath: func(name string) (string, error) {
@@ -148,6 +175,9 @@ func TestTorGetInfoFailure(t *testing.T) {
 		testTorStart: func(ctx context.Context, conf *tor.StartConf) (*tor.Tor, error) {
 			return &tor.Tor{}, nil
 		},
+		testTorProtocolInfo: func(tor *tor.Tor) (*control.ProtocolInfo, error) {
+			return &control.ProtocolInfo{}, nil
+		},
 		testTorEnableNetwork: func(ctx context.Context, tor *tor.Tor, wait bool) error {
 			return nil
 		},
@@ -165,7 +195,7 @@ func TestTorGetInfoFailure(t *testing.T) {
 
 func TestTorGetInfoInvalidNumberOfKeys(t *testing.T) {
 	ctx := context.Background()
-	tun, err := torStart(ctx, &Config{
+	tun, _, err := torStart(ctx, &Config{
 		Session:   &MockableSession{},
 		TunnelDir: "testdata",
 		testExecabsLookPath: func(name string) (string, error) {
@@ -174,6 +204,9 @@ func TestTorGetInfoInvalidNumberOfKeys(t *testing.T) {
 		testTorStart: func(ctx context.Context, conf *tor.StartConf) (*tor.Tor, error) {
 			return &tor.Tor{}, nil
 		},
+		testTorProtocolInfo: func(tor *tor.Tor) (*control.ProtocolInfo, error) {
+			return &control.ProtocolInfo{}, nil
+		},
 		testTorEnableNetwork: func(ctx context.Context, tor *tor.Tor, wait bool) error {
 			return nil
 		},
@@ -191,7 +224,7 @@ func TestTorGetInfoInvalidNumberOfKeys(t *testing.T) {
 
 func TestTorGetInfoInvalidKey(t *testing.T) {
 	ctx := context.Background()
-	tun, err := torStart(ctx, &Config{
+	tun, _, err := torStart(ctx, &Config{
 		Session:   &MockableSession{},
 		TunnelDir: "testdata",
 		testExecabsLookPath: func(name string) (string, error) {
@@ -200,6 +233,9 @@ func TestTorGetInfoInvalidKey(t *testing.T) {
 		testTorStart: func(ctx context.Context, conf *tor.StartConf) (*tor.Tor, error) {
 			return &tor.Tor{}, nil
 		},
+		testTorProtocolInfo: func(tor *tor.Tor) (*control.ProtocolInfo, error) {
+			return &control.ProtocolInfo{}, nil
+		},
 		testTorEnableNetwork: func(ctx context.Context, tor *tor.Tor, wait bool) error {
 			return nil
 		},
@@ -217,7 +253,7 @@ func TestTorGetInfoInvalidKey(t *testing.T) {
 
 func TestTorGetInfoInvalidProxyType(t *testing.T) {
 	ctx := context.Background()
-	tun, err := torStart(ctx, &Config{
+	tun, _, err := torStart(ctx, &Config{
 		Session:   &MockableSession{},
 		TunnelDir: "testdata",
 		testExecabsLookPath: func(name string) (string, error) {
@@ -226,6 +262,9 @@ func TestTorGetInfoInvalidProxyType(t *testing.T) {
 		testTorStart: func(ctx context.Context, conf *tor.StartConf) (*tor.Tor, error) {
 			return &tor.Tor{}, nil
 		},
+		testTorProtocolInfo: func(tor *tor.Tor) (*control.ProtocolInfo, error) {
+			return &control.ProtocolInfo{}, nil
+		},
 		testTorEnableNetwork: func(ctx context.Context, tor *tor.Tor, wait bool) error {
 			return nil
 		},
@@ -243,7 +282,7 @@ func TestTorGetInfoInvalidProxyType(t *testing.T) {
 
 func TestTorUnsupportedProxy(t *testing.T) {
 	ctx := context.Background()
-	tun, err := torStart(ctx, &Config{
+	tun, _, err := torStart(ctx, &Config{
 		Session:   &MockableSession{},
 		TunnelDir: "testdata",
 		testExecabsLookPath: func(name string) (string, error) {
@@ -252,6 +291,9 @@ func TestTorUnsupportedProxy(t *testing.T) {
 		testTorStart: func(ctx context.Context, conf *tor.StartConf) (*tor.Tor, error) {
 			return &tor.Tor{}, nil
 		},
+		testTorProtocolInfo: func(tor *tor.Tor) (*control.ProtocolInfo, error) {
+			return &control.ProtocolInfo{}, nil
+		},
 		testTorEnableNetwork: func(ctx context.Context, tor *tor.Tor, wait bool) error {
 			return nil
 		},

internal/tunnel/tunnel.go

@@ -74,6 +74,22 @@ var ErrEmptyTunnelDir = errors.New("TunnelDir is empty")
 // is not supported by this package.
 var ErrUnsupportedTunnelName = errors.New("unsupported tunnel name")
 
+// DebugInfo contains information useful to debug issues
+// when starting up a given tunnel fails.
+type DebugInfo struct {
+	// LogFilePath is the path to the log file, which MAY
+	// be empty in case we don't have a log file.
+	LogFilePath string
+
+	// Name is the name of the tunnel and will always
+	// be properly set by the code.
+	Name string
+
+	// Version is the tunnel version. This field MAY be
+	// empty if we don't know the version.
+	Version string
+}
+
 // Start starts a new tunnel by name or returns an error. We currently
 // support the following tunnels:
 //
@@ -94,7 +110,15 @@ var ErrUnsupportedTunnelName = errors.New("unsupported tunnel name")
 // The "fake" tunnel is a fake tunnel that just exposes a
 // SOCKS5 proxy and then connects directly to server. We use
 // this special kind of tunnel to implement tests.
-func Start(ctx context.Context, config *Config) (Tunnel, error) {
+//
+// The return value is a triple:
+//
+// 1. a valid Tunnel on success, nil on failure;
+//
+// 2. debugging information (both on success and failure);
+//
+// 3. nil on success, an error on failure.
+func Start(ctx context.Context, config *Config) (Tunnel, DebugInfo, error) {
 	switch config.Name {
 	case "fake":
 		return fakeStart(ctx, config)
@@ -103,6 +127,7 @@ func Start(ctx context.Context, config *Config) (Tunnel, error) {
 	case "tor":
 		return torStart(ctx, config)
 	default:
-		return nil, fmt.Errorf("%w: %s", ErrUnsupportedTunnelName, config.Name)
+		di := DebugInfo{}
+		return nil, di, fmt.Errorf("%w: %s", ErrUnsupportedTunnelName, config.Name)
 	}
 }

internal/tunnel/tunnel_test.go

@@ -10,7 +10,7 @@ import (
 
 func TestStartNoTunnel(t *testing.T) {
 	ctx := context.Background()
-	tun, err := tunnel.Start(ctx, &tunnel.Config{
+	tun, _, err := tunnel.Start(ctx, &tunnel.Config{
 		Name:    "",
 		Session: &tunnel.MockableSession{},
 	})
@@ -25,7 +25,7 @@ func TestStartNoTunnel(t *testing.T) {
 func TestStartPsiphonWithCancelledContext(t *testing.T) {
 	ctx, cancel := context.WithCancel(context.Background())
 	cancel() // fail immediately
-	tun, err := tunnel.Start(ctx, &tunnel.Config{
+	tun, _, err := tunnel.Start(ctx, &tunnel.Config{
 		Name:      "psiphon",
 		Session:   &tunnel.MockableSession{},
 		TunnelDir: "testdata",
@@ -41,7 +41,7 @@ func TestStartPsiphonWithCancelledContext(t *testing.T) {
 func TestStartTorWithCancelledContext(t *testing.T) {
 	ctx, cancel := context.WithCancel(context.Background())
 	cancel() // fail immediately
-	tun, err := tunnel.Start(ctx, &tunnel.Config{
+	tun, _, err := tunnel.Start(ctx, &tunnel.Config{
 		Name:      "tor",
 		Session:   &tunnel.MockableSession{},
 		TunnelDir: "testdata",
@@ -56,7 +56,7 @@ func TestStartTorWithCancelledContext(t *testing.T) {
 
 func TestStartInvalidTunnel(t *testing.T) {
 	ctx := context.Background()
-	tun, err := tunnel.Start(ctx, &tunnel.Config{
+	tun, _, err := tunnel.Start(ctx, &tunnel.Config{
 		Name:      "antani",
 		Session:   &tunnel.MockableSession{},
 		TunnelDir: "testdata",