fsocks5

README

A Simple and Configurable SOCKS5 Proxy Server in Go

A lightweight, configurable SOCKS5 proxy server written in Go.
It supports graceful shutdown, username/password authentication, and flexible logging.
This project is designed to be simple, reliable, and easy to deploy.

---

✨ Features

• SOCKS5 Protocol Support: Implements CONNECT (for TCP) and UDP ASSOCIATE commands.
• Authentication: Simple and secure username/password authentication.

---

🚀 Getting Started

Prerequisites

• Go 1.21 or later.

Installation

You can install the server directly using go install:

go install github.com/aomori446/fsocks5/socks@latest

Alternatively, you can clone the repository and build it from source:

# Clone the repository
git clone https://github.com/aomori446/fsocks5.git

# Navigate into the project directory
cd fsocks5/socks

# Build the binary
go build .

---

Usage

Run the server with the desired flags.
To see all available options, use the -h or --help flag:

./socks -h

Examples

1. Run with default settings
Listens on port :1080 with no authentication and info-level logging to the console.

./socks

2. Run on a different port with debug logging

./socks -addr="localhost:9090" -log-level=debug

3. Run with username/password authentication

./socks -user="myuser" -pass="mypassword123"

4. Run with logging to a file
Logs will be written to ./my-app-logs/server.log.
The directory will be created if it doesn't exist.

./socks -log-dir="./my-app-logs"

5. Run with custom timeouts
Sets a 30-second dial timeout and a 2-minute inactivity timeout.

./socks -dial-timeout=30 -activity-timeout=120

---

🔧 Configuration

All configuration is managed via command-line flags:

Flag	Description	Default
-addr	The address and port for the server to listen on.	:1080
-user	Username for authentication. Enables authentication if set with -pass.	(none)
-pass	Password for authentication. Enables authentication if set with -user.	(none)
-log-level	Log level (debug, info, warn, error).	info
-log-dir	Directory to write log files to. If empty, logs go to standard output.	(stdout)
-dial-timeout	Timeout for establishing outbound connections.	10s
-activity-timeout	Timeout for inactive connections.	30s

---

📄 License

This project is licensed under the MIT License.
See the LICENSE file for details.

Documentation

Index

• Variables
• func AddrToNetAddr(network string, a Addr) (net.Addr, error)
• func Auth(conn io.ReadWriter, author Authenticator) error
• func ReadExactFrom(conn io.Reader, n byte) ([]byte, error)
• func ReplyTo(conn io.Writer, message []byte) error
• func UDPAddrIsAllZero(addr Addr) bool
• type Addr
  • func AddrMarshal(addr net.Addr) Addr
  • func AddrUnmarshal(b []byte) (Addr, error)
• type AddressType
• type Authenticator
  • func (a Authenticator) SupportGSSAPI()
  • func (a Authenticator) SupportNoAuth()
  • func (a Authenticator) SupportUsernamePassword(hasUser func(name, password string) bool)
• type Command
  • func (c Command) Legal() bool
  • func (c Command) String() string
• type Config
• type Datagram
  • func (d *Datagram) SendBy(conn *net.UDPConn) error
• type DomainNameAddr
  • func (a *DomainNameAddr) Packet() []byte
  • func (a *DomainNameAddr) String() string
  • func (a *DomainNameAddr) Type() AddressType
• type EmptyAddr
  • func (e *EmptyAddr) Packet() []byte
  • func (e *EmptyAddr) String() string
  • func (e *EmptyAddr) Type() AddressType
• type Filed
• type IPv4Addr
  • func (a *IPv4Addr) Packet() []byte
  • func (a *IPv4Addr) String() string
  • func (a *IPv4Addr) Type() AddressType
• type IPv6Addr
  • func (a *IPv6Addr) Packet() []byte
  • func (a *IPv6Addr) String() string
  • func (a *IPv6Addr) Type() AddressType
• type Relayer
  • func NewRelayer(ctx context.Context, conn *net.UDPConn, logger *slog.Logger, ...) *Relayer
  • func (r *Relayer) PacketDatagram(s *session, from net.Addr, data []byte) (*Datagram, error)
  • func (r *Relayer) Relay()
  • func (r *Relayer) UnPacketDatagram(data []byte) (*Datagram, error)
• type Request
  • func ReadRequest(conn io.Reader) (*Request, error)
• type Response
  • func NewResponse(filed Filed, addr Addr) *Response
  • func (r *Response) Packet() []byte
• type RuleSet
  • func (r RuleSet) Allow(c Command)
  • func (r RuleSet) Allowed(c Command) bool
• type Server
  • func NewServer(config Config) *Server
  • func (s *Server) ListenAndServe(ctx context.Context, address string) error
  • func (s *Server) Serve(ctx context.Context, ln *net.TCPListener) error

Variables

var (
	ErrAuthFormat              = errors.New("auth: invalid format")
	ErrAuthNoAcceptableMethods = errors.New("auth: no acceptable methods")
	ErrAuthMethodFormat        = errors.New("auth: invalid method format")
)

var (
	ErrRequestFormat  = errors.New("request: invalid format")
	ErrRequestCommand = errors.New("request: command not support")
)

var (
	ErrDatagramFormat = errors.New("UDP Associate Datagram format error")
)

var (
	// ErrSocksVersion is returned when the SOCKS version requested by the client is not 5.
	ErrSocksVersion = errors.New("version not support")
)

Functions

func AddrToNetAddr

func AddrToNetAddr(network string, a Addr) (net.Addr, error)

func Auth

func Auth(conn io.ReadWriter, author Authenticator) error

func ReadExactFrom

func ReadExactFrom(conn io.Reader, n byte) ([]byte, error)

func ReplyTo

func ReplyTo(conn io.Writer, message []byte) error

func UDPAddrIsAllZero

func UDPAddrIsAllZero(addr Addr) bool

Types

type Addr

type Addr interface {
	Type() AddressType
	String() string
	Packet() []byte
}

func AddrMarshal

func AddrMarshal(addr net.Addr) Addr

func AddrUnmarshal

func AddrUnmarshal(b []byte) (Addr, error)

type AddressType

type AddressType byte

const (
	IPv4       AddressType = 0x01
	DomainName AddressType = 0x03
	IPv6       AddressType = 0x04
)

type Authenticator

type Authenticator map[byte]func(io.ReadWriter) error

func (Authenticator) SupportGSSAPI

func (a Authenticator) SupportGSSAPI()

func (Authenticator) SupportNoAuth

func (a Authenticator) SupportNoAuth()

func (Authenticator) SupportUsernamePassword

func (a Authenticator) SupportUsernamePassword(hasUser func(name, password string) bool)

type Command

type Command byte

const (
	Connect      Command = 0x01
	Bind         Command = 0x02
	UDPAssociate Command = 0x03
)

func (Command) Legal

func (c Command) Legal() bool

func (Command) String

func (c Command) String() string

type Config

type Config struct {
	// Authenticator specifies the authentication methods supported by the server.
	// If not set, no authentication is required by default.
	Authenticator Authenticator
	// RuleSet defines the rules for allowing or denying SOCKS commands.
	// If not set, only the CONNECT command is allowed by default.
	RuleSet RuleSet
	// Logger specifies the logger to use.
	// If nil, a default text logger that writes to stdout will be used.
	Logger *slog.Logger

	// DialTimeout is the timeout for establishing a connection to the destination.
	// Defaults to 10 seconds if not set.
	DialTimeout time.Duration
	// ActivityTimeout is the timeout for inactivity on a connection.
	// Connections with no activity for this duration will be closed.
	// Defaults to 30 seconds if not set.
	ActivityTimeout time.Duration
}

Config configures a SOCKS5 server.

type Datagram

type Datagram struct {
	DstAddr Addr
	Data    []byte
}

func (*Datagram) SendBy

func (d *Datagram) SendBy(conn *net.UDPConn) error

type DomainNameAddr

type DomainNameAddr struct {
	// contains filtered or unexported fields
}

DomainNameAddr 表示域名與埠

func (*DomainNameAddr) Packet

func (a *DomainNameAddr) Packet() []byte

func (*DomainNameAddr) String

func (a *DomainNameAddr) String() string

String returns the domain name and port, for example: www.example.com:443

func (*DomainNameAddr) Type

func (a *DomainNameAddr) Type() AddressType

type EmptyAddr

type EmptyAddr struct{}

EmptyAddr indicates an empty address, used to return an error Response

func (*EmptyAddr) Packet

func (e *EmptyAddr) Packet() []byte

func (*EmptyAddr) String

func (e *EmptyAddr) String() string

func (*EmptyAddr) Type

func (e *EmptyAddr) Type() AddressType

type Filed

type Filed byte

const (
	Succeeded               Filed = 0x00
	GeneralFailure          Filed = 0x01
	CommandNotSupported     Filed = 0x07
	AddressTypeNotSupported Filed = 0x08
)

type IPv4Addr

type IPv4Addr struct {
	// contains filtered or unexported fields
}

IPv4Addr represents IPv4 address and port

func (*IPv4Addr) Packet

func (a *IPv4Addr) Packet() []byte

func (*IPv4Addr) String

func (a *IPv4Addr) String() string

func (*IPv4Addr) Type

func (a *IPv4Addr) Type() AddressType

type IPv6Addr

type IPv6Addr struct {
	// contains filtered or unexported fields
}

IPv6Addr 表示 IPv6 地址與埠

func (*IPv6Addr) Packet

func (a *IPv6Addr) Packet() []byte

func (*IPv6Addr) String

func (a *IPv6Addr) String() string

func (*IPv6Addr) Type

func (a *IPv6Addr) Type() AddressType

type Relayer

type Relayer struct {
	// contains filtered or unexported fields
}

func NewRelayer

func NewRelayer(ctx context.Context, conn *net.UDPConn, logger *slog.Logger, timeout time.Duration, expectedAddr net.Addr) *Relayer

func (*Relayer) PacketDatagram

func (r *Relayer) PacketDatagram(s *session, from net.Addr, data []byte) (*Datagram, error)

func (*Relayer) Relay

func (r *Relayer) Relay()

func (*Relayer) UnPacketDatagram

func (r *Relayer) UnPacketDatagram(data []byte) (*Datagram, error)

type Request

type Request struct {
	CMD     Command
	DstAddr Addr
}

func ReadRequest

func ReadRequest(conn io.Reader) (*Request, error)

type Response

type Response struct {
	Version byte
	Filed   Filed
	BndAddr Addr
}

func NewResponse

func NewResponse(filed Filed, addr Addr) *Response

func (*Response) Packet

func (r *Response) Packet() []byte

type RuleSet

type RuleSet map[Command]bool

func (RuleSet) Allow

func (r RuleSet) Allow(c Command)

func (RuleSet) Allowed

func (r RuleSet) Allowed(c Command) bool

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server represents a SOCKS5 proxy server.

func NewServer

func NewServer(config Config) *Server

NewServer creates a new SOCKS5 Server with the given configuration. It provides sensible defaults for any unset options.

func (*Server) ListenAndServe

func (s *Server) ListenAndServe(ctx context.Context, address string) error

ListenAndServe listens on the TCP network address and then calls Serve to handle requests. If the address is empty, it defaults to the SOCKS5 standard port 1080.

func (*Server) Serve

func (s *Server) Serve(ctx context.Context, ln *net.TCPListener) error

Serve accepts incoming connections on the listener and handles them concurrently. It blocks until the context is canceled and gracefully waits for all active connections to finish.