feat(example): add Outline CLI app for Linux

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)
+	}
+}