feat(portforwarding): Allow running script upon port forwarding success

Dockerfile

@@ -125,6 +125,7 @@ ENV VPN_SERVICE_PROVIDER=pia \
     VPN_PORT_FORWARDING_STATUS_FILE="/tmp/gluetun/forwarded_port" \
     VPN_PORT_FORWARDING_USERNAME= \
     VPN_PORT_FORWARDING_PASSWORD= \
+    VPN_PORT_FORWARDING_UP_COMMAND= \
     # # Cyberghost only:
     OPENVPN_CERT= \
     OPENVPN_KEY= \

cmd/gluetun/main.go

@@ -380,7 +380,7 @@ func _main(ctx context.Context, buildInfo models.BuildInformation,
 
 	portForwardLogger := logger.New(log.SetComponent("port forwarding"))
 	portForwardLooper := portforward.NewLoop(allSettings.VPN.Provider.PortForwarding,
-		routingConf, httpClient, firewallConf, portForwardLogger, puid, pgid)
+		routingConf, httpClient, firewallConf, portForwardLogger, cmder, puid, pgid)
 	portForwardRunError, err := portForwardLooper.Start(ctx)
 	if err != nil {
 		return fmt.Errorf("starting port forwarding loop: %w", err)

internal/command/split.go

@@ -0,0 +1,150 @@
+package command
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"strings"
+	"unicode/utf8"
+)
+
+var (
+	ErrCommandEmpty            = errors.New("command is empty")
+	ErrSingleQuoteUnterminated = errors.New("unterminated single-quoted string")
+	ErrDoubleQuoteUnterminated = errors.New("unterminated double-quoted string")
+	ErrEscapeUnterminated      = errors.New("unterminated backslash-escape")
+)
+
+// Split splits a command string into a slice of arguments.
+// This is especially important for commands such as:
+// /bin/sh -c "echo hello"
+// which should be split into: ["/bin/sh", "-c", "echo hello"]
+// It supports backslash-escapes, single-quotes and double-quotes.
+// It does not support:
+// - the $" quoting style.
+// - expansion (brace, shell or pathname).
+func Split(command string) (words []string, err error) {
+	if command == "" {
+		return nil, fmt.Errorf("%w", ErrCommandEmpty)
+	}
+
+	const bufferSize = 1024
+	buffer := bytes.NewBuffer(make([]byte, bufferSize))
+
+	startIndex := 0
+
+	for startIndex < len(command) {
+		// skip any split characters at the start
+		character, runeSize := utf8.DecodeRuneInString(command[startIndex:])
+		switch {
+		case strings.ContainsRune(" \n\t", character):
+			startIndex += runeSize
+		case character == '\\':
+			// Look ahead to eventually skip an escaped newline
+			if command[startIndex+runeSize:] == "" {
+				return nil, fmt.Errorf("%w: %q", ErrEscapeUnterminated, command)
+			}
+			character, runeSize := utf8.DecodeRuneInString(command[startIndex+runeSize:])
+			if character == '\n' {
+				startIndex += runeSize + runeSize // backslash and newline
+			}
+		default:
+			var word string
+			buffer.Reset()
+			word, startIndex, err = splitWord(command, startIndex, buffer)
+			if err != nil {
+				return nil, fmt.Errorf("splitting word in %q: %w", command, err)
+			}
+			words = append(words, word)
+		}
+	}
+	return words, nil
+}
+
+// WARNING: buffer must be cleared before calling this function.
+func splitWord(input string, startIndex int, buffer *bytes.Buffer) (
+	word string, newStartIndex int, err error,
+) {
+	cursor := startIndex
+	for cursor < len(input) {
+		character, runeLength := utf8.DecodeRuneInString(input[cursor:])
+		cursor += runeLength
+		if character == '"' ||
+			character == '\'' ||
+			character == '\\' ||
+			character == ' ' ||
+			character == '\n' ||
+			character == '\t' {
+			buffer.WriteString(input[startIndex : cursor-runeLength])
+		}
+
+		switch {
+		case strings.ContainsRune(" \n\t", character): // spacing character
+			return buffer.String(), cursor, nil
+		case character == '"':
+			return handleDoubleQuoted(input, cursor, buffer)
+		case character == '\'':
+			return handleSingleQuoted(input, cursor, buffer)
+		case character == '\\':
+			return handleEscaped(input, cursor, buffer)
+		}
+	}
+
+	buffer.WriteString(input[startIndex:])
+	return buffer.String(), len(input), nil
+}
+
+func handleDoubleQuoted(input string, startIndex int, buffer *bytes.Buffer) (
+	word string, newStartIndex int, err error,
+) {
+	cursor := startIndex
+	for cursor < len(input) {
+		nextCharacter, nextRuneLength := utf8.DecodeRuneInString(input[cursor:])
+		cursor += nextRuneLength
+		switch nextCharacter {
+		case '"': // end of the double quoted string
+			buffer.WriteString(input[startIndex : cursor-nextRuneLength])
+			return splitWord(input, cursor, buffer)
+		case '\\': // escaped character
+			escapedCharacter, escapedRuneLength := utf8.DecodeRuneInString(input[cursor:])
+			cursor += escapedRuneLength
+			if !strings.ContainsRune("$`\"\n\\", escapedCharacter) {
+				break
+			}
+			buffer.WriteString(input[startIndex : cursor-nextRuneLength-escapedRuneLength])
+			if escapedCharacter != '\n' {
+				// skip backslash entirely for the newline character
+				buffer.WriteRune(escapedCharacter)
+			}
+			startIndex = cursor
+		}
+	}
+	return "", 0, fmt.Errorf("%w", ErrDoubleQuoteUnterminated)
+}
+
+func handleSingleQuoted(input string, startIndex int, buffer *bytes.Buffer) (
+	word string, newStartIndex int, err error,
+) {
+	closingQuoteIndex := strings.IndexRune(input[startIndex:], '\'')
+	if closingQuoteIndex == -1 {
+		return "", 0, fmt.Errorf("%w", ErrSingleQuoteUnterminated)
+	}
+	buffer.WriteString(input[startIndex : startIndex+closingQuoteIndex])
+	const singleQuoteRuneLength = 1
+	startIndex += closingQuoteIndex + singleQuoteRuneLength
+	return splitWord(input, startIndex, buffer)
+}
+
+func handleEscaped(input string, startIndex int, buffer *bytes.Buffer) (
+	word string, newStartIndex int, err error,
+) {
+	if input[startIndex:] == "" {
+		return "", 0, fmt.Errorf("%w", ErrEscapeUnterminated)
+	}
+	character, runeLength := utf8.DecodeRuneInString(input[startIndex:])
+	if character != '\n' { // backslash-escaped newline is ignored
+		buffer.WriteString(input[startIndex : startIndex+runeLength])
+	}
+	startIndex += runeLength
+	return splitWord(input, startIndex, buffer)
+}

internal/command/split_test.go

@@ -0,0 +1,110 @@
+package command
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func Test_Split(t *testing.T) {
+	t.Parallel()
+
+	testCases := map[string]struct {
+		command    string
+		words      []string
+		errWrapped error
+		errMessage string
+	}{
+		"empty": {
+			command:    "",
+			errWrapped: ErrCommandEmpty,
+			errMessage: "command is empty",
+		},
+		"concrete_sh_command": {
+			command: `/bin/sh -c "echo 123"`,
+			words:   []string{"/bin/sh", "-c", "echo 123"},
+		},
+		"single_word": {
+			command: "word1",
+			words:   []string{"word1"},
+		},
+		"two_words_single_space": {
+			command: "word1 word2",
+			words:   []string{"word1", "word2"},
+		},
+		"two_words_multiple_space": {
+			command: "word1    word2",
+			words:   []string{"word1", "word2"},
+		},
+		"two_words_no_expansion": {
+			command: "word1*    word2?",
+			words:   []string{"word1*", "word2?"},
+		},
+		"escaped_single quote": {
+			command: "ain\\'t good",
+			words:   []string{"ain't", "good"},
+		},
+		"escaped_single_quote_all_single_quoted": {
+			command: "'ain'\\''t good'",
+			words:   []string{"ain't good"},
+		},
+		"empty_single_quoted": {
+			command: "word1 ''  word2",
+			words:   []string{"word1", "", "word2"},
+		},
+		"escaped_newline": {
+			command: "word1\\\nword2",
+			words:   []string{"word1word2"},
+		},
+		"quoted_newline": {
+			command: "text \"with\na\" quoted newline",
+			words:   []string{"text", "with\na", "quoted", "newline"},
+		},
+		"quoted_escaped_newline": {
+			command: "\"word1\\d\\\\\\\" word2\\\nword3 word4\"",
+			words:   []string{"word1\\d\\\" word2word3 word4"},
+		},
+		"escaped_separated_newline": {
+			command: "word1 \\\n word2",
+			words:   []string{"word1", "word2"},
+		},
+		"double_quotes_no_spacing": {
+			command: "word1\"word2\"word3",
+			words:   []string{"word1word2word3"},
+		},
+		"unterminated_single_quote": {
+			command:    "'abc'\\''def",
+			errWrapped: ErrSingleQuoteUnterminated,
+			errMessage: `splitting word in "'abc'\\''def": unterminated single-quoted string`,
+		},
+		"unterminated_double_quote": {
+			command:    "\"abc'def",
+			errWrapped: ErrDoubleQuoteUnterminated,
+			errMessage: `splitting word in "\"abc'def": unterminated double-quoted string`,
+		},
+		"unterminated_escape": {
+			command:    "abc\\",
+			errWrapped: ErrEscapeUnterminated,
+			errMessage: `splitting word in "abc\\": unterminated backslash-escape`,
+		},
+		"unterminated_escape_only": {
+			command:    "   \\",
+			errWrapped: ErrEscapeUnterminated,
+			errMessage: `unterminated backslash-escape: "   \\"`,
+		},
+	}
+
+	for name, testCase := range testCases {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			words, err := Split(testCase.command)
+
+			assert.Equal(t, testCase.words, words)
+			assert.ErrorIs(t, err, testCase.errWrapped)
+			if testCase.errWrapped != nil {
+				assert.EqualError(t, err, testCase.errMessage)
+			}
+		})
+	}
+}

internal/configuration/settings/portforward.go

@@ -29,6 +29,10 @@ type PortForwarding struct {
 	// to write to a file. It cannot be nil for the
 	// internal state
 	Filepath *string `json:"status_file_path"`
+	// UpCommand is the command to use when the port forwarding is up.
+	// It can be the empty string to indicate not to run a command.
+	// It cannot be nil in the internal state.
+	UpCommand *string `json:"up_command"`
 	// ListeningPort is the port traffic would be redirected to from the
 	// forwarded port. The redirection is disabled if it is set to 0, which
 	// is its default as well.
@@ -84,6 +88,7 @@ func (p *PortForwarding) Copy() (copied PortForwarding) {
 		Enabled:       gosettings.CopyPointer(p.Enabled),
 		Provider:      gosettings.CopyPointer(p.Provider),
 		Filepath:      gosettings.CopyPointer(p.Filepath),
+		UpCommand:     gosettings.CopyPointer(p.UpCommand),
 		ListeningPort: gosettings.CopyPointer(p.ListeningPort),
 		Username:      p.Username,
 		Password:      p.Password,
@@ -94,6 +99,7 @@ func (p *PortForwarding) OverrideWith(other PortForwarding) {
 	p.Enabled = gosettings.OverrideWithPointer(p.Enabled, other.Enabled)
 	p.Provider = gosettings.OverrideWithPointer(p.Provider, other.Provider)
 	p.Filepath = gosettings.OverrideWithPointer(p.Filepath, other.Filepath)
+	p.UpCommand = gosettings.OverrideWithPointer(p.UpCommand, other.UpCommand)
 	p.ListeningPort = gosettings.OverrideWithPointer(p.ListeningPort, other.ListeningPort)
 	p.Username = gosettings.OverrideWithComparable(p.Username, other.Username)
 	p.Password = gosettings.OverrideWithComparable(p.Password, other.Password)
@@ -103,6 +109,7 @@ func (p *PortForwarding) setDefaults() {
 	p.Enabled = gosettings.DefaultPointer(p.Enabled, false)
 	p.Provider = gosettings.DefaultPointer(p.Provider, "")
 	p.Filepath = gosettings.DefaultPointer(p.Filepath, "/tmp/gluetun/forwarded_port")
+	p.UpCommand = gosettings.DefaultPointer(p.UpCommand, "")
 	p.ListeningPort = gosettings.DefaultPointer(p.ListeningPort, 0)
 }
 
@@ -135,6 +142,11 @@ func (p PortForwarding) toLinesNode() (node *gotree.Node) {
 	}
 	node.Appendf("Forwarded port file path: %s", filepath)
 
+	command := *p.UpCommand
+	if command != "" {
+		node.Appendf("Forwarded port command: %s", command)
+	}
+
 	if p.Username != "" {
 		credentialsNode := node.Appendf("Credentials:")
 		credentialsNode.Appendf("Username: %s", p.Username)
@@ -163,6 +175,9 @@ func (p *PortForwarding) read(r *reader.Reader) (err error) {
 			"PRIVATE_INTERNET_ACCESS_VPN_PORT_FORWARDING_STATUS_FILE",
 		))
 
+	p.UpCommand = r.Get("VPN_PORT_FORWARDING_UP_COMMAND",
+		reader.ForceLowercase(false))
+
 	p.ListeningPort, err = r.Uint16Ptr("VPN_PORT_FORWARDING_LISTENING_PORT")
 	if err != nil {
 		return err

internal/portforward/interfaces.go

@@ -3,6 +3,7 @@ package portforward
 import (
 	"context"
 	"net/netip"
+	"os/exec"
 )
 
 type Service interface {
@@ -29,3 +30,8 @@ type Logger interface {
 	Warn(s string)
 	Error(s string)
 }
+
+type Cmder interface {
+	Start(cmd *exec.Cmd) (stdoutLines, stderrLines <-chan string,
+		waitError <-chan error, startErr error)
+}

internal/portforward/loop.go

@@ -20,6 +20,7 @@ type Loop struct {
 	client      *http.Client
 	portAllower PortAllower
 	logger      Logger
+	cmder       Cmder
 	// Fixed parameters
 	uid, gid int
 	// Internal channels and locks
@@ -34,21 +35,23 @@ type Loop struct {
 
 func NewLoop(settings settings.PortForwarding, routing Routing,
 	client *http.Client, portAllower PortAllower,
-	logger Logger, uid, gid int,
+	logger Logger, cmder Cmder, uid, gid int,
 ) *Loop {
 	return &Loop{
 		settings: Settings{
 			VPNIsUp: ptrTo(false),
 			Service: service.Settings{
 				Enabled:       settings.Enabled,
 				Filepath:      *settings.Filepath,
+				UpCommand:     *settings.UpCommand,
 				ListeningPort: *settings.ListeningPort,
 			},
 		},
 		routing:     routing,
 		client:      client,
 		portAllower: portAllower,
 		logger:      logger,
+		cmder:       cmder,
 		uid:         uid,
 		gid:         gid,
 	}
@@ -115,7 +118,7 @@ func (l *Loop) run(runCtx context.Context, runDone chan<- struct{},
 		*serviceSettings.Enabled = *serviceSettings.Enabled && *l.settings.VPNIsUp
 
 		l.service = service.New(serviceSettings, l.routing, l.client,
-			l.portAllower, l.logger, l.uid, l.gid)
+			l.portAllower, l.logger, l.cmder, l.uid, l.gid)
 
 		var err error
 		serviceRunError, err = l.service.Start(runCtx)