feat(example): add Outline CLI app for Linux (#15)

I added the OutlineVPN command-line application for Linux. The application utilizes the latest SDK features to establish TCP and UDP traffic handlers. Additionally, it leverages best practices for setting up multiple routing tables for VPN services on Linux systems.

#### Linux

<img width="1033" alt="image" src="https://github.com/Jigsaw-Code/outline-sdk/assets/93548144/6c56b7c4-6189-471a-9058-21b32c4c9d0c">

#### Non-Linux

<img width="336" alt="image" src="https://github.com/Jigsaw-Code/outline-sdk/assets/93548144/50b4531f-f1f5-4173-9a17-9d19055a3f5a">

README.md

@@ -123,13 +123,12 @@ Beta features:
 
 - Integration resources
   - For Mobile apps
-    - [x] Library to run a local SOCKS5 or HTTP-Connect proxy ([source](./x/mobileproxy/mobileproxy.go), [example Go usage](./x/examples/fetch-proxy/main.go), [example mobile usage](./x/examples/mobileproxy)). (v0.0.6)
-    - [x] Documentation on how to integrate the SDK into mobile apps (v0.0.6)
-    - [x] Connectivity Test iOS mobile app using [Capacitor](https://capacitorjs.com/)
-    - [ ] Connectivity Test Android app using [Capacitor](https://capacitorjs.com/) (coming soon)
+    - [x] Library to run a local SOCKS5 or HTTP-Connect proxy ([source](./x/mobileproxy/mobileproxy.go), [example Go usage](./x/examples/fetch-proxy/main.go), [example mobile usage](./x/examples/mobileproxy)).
+    - [x] Documentation on how to integrate the SDK into mobile apps
+    - [x] Connectivity Test mobile app (iOS and Android) using [Capacitor](https://capacitorjs.com/)
   - For Go apps
     - [x] Connectivity Test example [Wails](https://wails.io/) graphical app
-    - [x] Connectivity Test example command-line app ([source](./x/examples/outline-connectivity/)) (v0.0.6)
-    - [ ] Outline Client example command-line app (coming soon)
-    - [x] Page fetch example command-line app ([source](./x/examples/outline-fetch/)) (v0.0.6)
-    - [x] Local proxy example command-line app ([source](./x/examples/http2transport/)) (v0.0.6)
+    - [x] Connectivity Test example command-line app ([source](./x/examples/outline-connectivity/))
+    - [x] Outline Client example command-line app ([source](./x/examples/outline-cli/))
+    - [x] Page fetch example command-line app ([source](./x/examples/outline-fetch/))
+    - [x] Local proxy example command-line app ([source](./x/examples/http2transport/))

x/config/config.go

@@ -119,3 +119,25 @@ func newPacketDialerFromPart(innerDialer transport.PacketDialer, oneDialerConfig
 		return nil, fmt.Errorf("config scheme '%v' is not supported", url.Scheme)
 	}
 }
+
+// NewpacketListener creates a new [transport.PacketListener] according to the given config,
+// the config must contain only one "ss://" segment.
+func NewpacketListener(transportConfig string) (transport.PacketListener, error) {
+	if transportConfig = strings.TrimSpace(transportConfig); transportConfig == "" {
+		return nil, errors.New("config is required")
+	}
+	if strings.Contains(transportConfig, "|") {
+		return nil, errors.New("multi-part config is not supported")
+	}
+
+	url, err := url.Parse(transportConfig)
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse config: %w", err)
+	}
+	if url.Scheme != "ss" {
+		return nil, errors.New("config scheme must be 'ss' for a PacketListener")
+	}
+
+	// TODO: support nested dialer, the last part must be "ss://"
+	return newShadowsocksPacketListenerFromURL(url)
+}

x/config/shadowsocks.go

@@ -55,6 +55,16 @@ func newShadowsocksPacketDialerFromURL(innerDialer transport.PacketDialer, confi
 	return dialer, nil
 }
 
+func newShadowsocksPacketListenerFromURL(configURL *url.URL) (transport.PacketListener, error) {
+	config, err := parseShadowsocksURL(configURL)
+	if err != nil {
+		return nil, err
+	}
+	// TODO: accept an inner dialer from the caller and pass it to UDPEndpoint
+	ep := &transport.UDPEndpoint{Address: config.serverAddress}
+	return shadowsocks.NewPacketListener(ep, config.cryptoKey)
+}
+
 type shadowsocksConfig struct {
 	serverAddress string
 	cryptoKey     *shadowsocks.EncryptionKey

x/examples/outline-cli/README.md

@@ -0,0 +1,23 @@
+# Outline VPN Command-Line Client
+
+A CLI interface of Outline VPN client for Linux.
+
+### Usage
+
+```
+go run github.com/Jigsaw-Code/outline-sdk/x/examples/outline-cli@latest -transport "ss://<outline-server-access-key>"
+```
+
+- `-transport` : the Outline server access key from the service provider, it should start with "ss://"
+
+### Build
+
+You can use the following command to build the CLI.
+
+
+```
+cd outline-sdk/x/examples/
+go build -o outline-cli  -ldflags="-extldflags=-static" ./outline-cli
+```
+
+> 💡 `cgo` will pull in the C runtime. By default, the C runtime is linked as a dynamic library. Sometimes this can cause problems when running the binary on different versions or distributions of Linux. To avoid this, we have added the `-ldflags="-extldflags=-static"` option. But if you only need to run the binary on the same machine, you can omit this option.

x/examples/outline-cli/app.go

@@ -0,0 +1,30 @@
+// Copyright 2023 Jigsaw Operations LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+type App struct {
+	TransportConfig *string
+	RoutingConfig   *RoutingConfig
+}
+
+type RoutingConfig struct {
+	TunDeviceName        string
+	TunDeviceIP          string
+	TunDeviceMTU         int
+	TunGatewayCIDR       string
+	RoutingTableID       int
+	RoutingTablePriority int
+	DNSServerIP          string
+}

x/examples/outline-cli/app_linux.go

@@ -0,0 +1,81 @@
+// Copyright 2023 Jigsaw Operations LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"os/signal"
+	"sync"
+
+	"golang.org/x/sys/unix"
+)
+
+func (app App) Run() error {
+	// this WaitGroup must Wait() after tun is closed
+	trafficCopyWg := &sync.WaitGroup{}
+	defer trafficCopyWg.Wait()
+
+	tun, err := newTunDevice(app.RoutingConfig.TunDeviceName, app.RoutingConfig.TunDeviceIP)
+	if err != nil {
+		return fmt.Errorf("failed to create tun device: %w", err)
+	}
+	defer tun.Close()
+
+	// disable IPv6 before resolving Shadowsocks server IP
+	prevIPv6, err := enableIPv6(false)
+	if err != nil {
+		return fmt.Errorf("failed to disable IPv6: %w", err)
+	}
+	defer enableIPv6(prevIPv6)
+
+	ss, err := NewOutlineDevice(*app.TransportConfig)
+	if err != nil {
+		return fmt.Errorf("failed to create OutlineDevice: %w", err)
+	}
+	defer ss.Close()
+
+	ss.Refresh()
+
+	// Copy the traffic from tun device to OutlineDevice bidirectionally
+	trafficCopyWg.Add(2)
+	go func() {
+		defer trafficCopyWg.Done()
+		written, err := io.Copy(ss, tun)
+		logging.Info.Printf("tun -> OutlineDevice stopped: %v %v\n", written, err)
+	}()
+	go func() {
+		defer trafficCopyWg.Done()
+		written, err := io.Copy(tun, ss)
+		logging.Info.Printf("OutlineDevice -> tun stopped: %v %v\n", written, err)
+	}()
+
+	if err := setSystemDNSServer(app.RoutingConfig.DNSServerIP); err != nil {
+		return fmt.Errorf("failed to configure system DNS: %w", err)
+	}
+	defer restoreSystemDNSServer()
+
+	if err := startRouting(ss.GetServerIP().String(), app.RoutingConfig); err != nil {
+		return fmt.Errorf("failed to configure routing: %w", err)
+	}
+	defer stopRouting(app.RoutingConfig.RoutingTableID)
+
+	sigc := make(chan os.Signal, 1)
+	signal.Notify(sigc, os.Interrupt, unix.SIGTERM, unix.SIGHUP)
+	s := <-sigc
+	logging.Info.Printf("received %v, terminating...\n", s)
+	return nil
+}

x/examples/outline-cli/app_other.go

@@ -0,0 +1,23 @@
+// Copyright 2023 Jigsaw Operations LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:build !linux
+
+package main
+
+import "errors"
+
+func (App) Run() error {
+	return errors.New("platform not supported")
+}

x/examples/outline-cli/dns_linux.go

@@ -0,0 +1,66 @@
+// Copyright 2023 Jigsaw Operations LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"fmt"
+	"os"
+)
+
+// todo: find a more portable way of configuring DNS (e.g. resolved)
+const (
+	resolvConfFile           = "/etc/resolv.conf"
+	resolvConfHeadFile       = "/etc/resolv.conf.head"
+	resolvConfBackupFile     = "/etc/resolv.outlinecli.backup"
+	resolvConfHeadBackupFile = "/etc/resolv.head.outlinecli.backup"
+)
+
+func setSystemDNSServer(serverHost string) error {
+	setting := []byte(`# Outline CLI DNS Setting
+# The original file has been renamed as resolv[.head].outlinecli.backup
+nameserver ` + serverHost + "\n")
+
+	if err := backupAndWriteFile(resolvConfFile, resolvConfBackupFile, setting); err != nil {
+		return err
+	}
+	return backupAndWriteFile(resolvConfHeadFile, resolvConfHeadBackupFile, setting)
+}
+
+func restoreSystemDNSServer() {
+	restoreFileIfExists(resolvConfBackupFile, resolvConfFile)
+	restoreFileIfExists(resolvConfHeadBackupFile, resolvConfHeadFile)
+}
+
+func backupAndWriteFile(original, backup string, data []byte) error {
+	if err := os.Rename(original, backup); err != nil {
+		return fmt.Errorf("failed to backup DNS config file '%s' to '%s': %w", original, backup, err)
+	}
+	if err := os.WriteFile(original, data, 0644); err != nil {
+		return fmt.Errorf("failed to write DNS config file '%s': %w", original, err)
+	}
+	return nil
+}
+
+func restoreFileIfExists(backup, original string) {
+	if _, err := os.Stat(backup); err != nil {
+		logging.Warn.Printf("no DNS config backup file '%s' presents: %v\n", backup, err)
+		return
+	}
+	if err := os.Rename(backup, original); err != nil {
+		logging.Err.Printf("failed to restore DNS config from backup '%s' to '%s': %v\n", backup, original, err)
+		return
+	}
+	logging.Info.Printf("DNS config restored from '%s' to '%s'\n", backup, original)
+}

x/examples/outline-cli/ipv6_linux.go

@@ -0,0 +1,49 @@
+// Copyright 2023 Jigsaw Operations LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"fmt"
+	"os"
+)
+
+const disableIPv6ProcFile = "/proc/sys/net/ipv6/conf/all/disable_ipv6"
+
+// enableIPv6 enables or disables the IPv6 support for the Linux system.
+// It returns the previous setting value so the caller can restore it.
+// Non-nil error means we cannot find the IPv6 setting.
+func enableIPv6(enabled bool) (bool, error) {
+	disabledStr, err := os.ReadFile(disableIPv6ProcFile)
+	if err != nil {
+		return false, fmt.Errorf("failed to read IPv6 config: %w", err)
+	}
+	if disabledStr[0] != '0' && disabledStr[0] != '1' {
+		return false, fmt.Errorf("invalid IPv6 config value: %v", disabledStr)
+	}
+
+	prevEnabled := disabledStr[0] == '0'
+
+	if enabled {
+		disabledStr[0] = '0'
+	} else {
+		disabledStr[0] = '1'
+	}
+	if err := os.WriteFile(disableIPv6ProcFile, disabledStr, 0644); err != nil {
+		return prevEnabled, fmt.Errorf("failed to write IPv6 config: %w", err)
+	}
+
+	logging.Info.Printf("updated global IPv6 support: %v\n", enabled)
+	return prevEnabled, nil
+}

x/examples/outline-cli/main.go

@@ -0,0 +1,55 @@
+// Copyright 2023 Jigsaw Operations LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"flag"
+	"fmt"
+	"io"
+	"log"
+	"os"
+)
+
+var logging = &struct {
+	Debug, Info, Warn, Err *log.Logger
+}{
+	Debug: log.New(io.Discard, "[DEBUG] ", log.LstdFlags),
+	Info:  log.New(os.Stdout, "[INFO] ", log.LstdFlags),
+	Warn:  log.New(os.Stderr, "[WARN] ", log.LstdFlags),
+	Err:   log.New(os.Stderr, "[ERROR] ", log.LstdFlags),
+}
+
+// ./app -transport "ss://..."
+func main() {
+	fmt.Println("OutlineVPN CLI (experimental)")
+
+	app := App{
+		TransportConfig: flag.String("transport", "", "Transport config"),
+		RoutingConfig: &RoutingConfig{
+			TunDeviceName:        "outline233",
+			TunDeviceIP:          "10.233.233.1",
+			TunDeviceMTU:         1500, // todo: read this from netlink
+			TunGatewayCIDR:       "10.233.233.2/32",
+			RoutingTableID:       233,
+			RoutingTablePriority: 23333,
+			DNSServerIP:          "9.9.9.9",
+		},
+	}
+	flag.Parse()
+
+	if err := app.Run(); err != nil {
+		logging.Err.Printf("%v\n", err)
+	}
+}