Go SOCKS5 Proxy Server

A lightweight, secure, and feature-rich SOCKS5 proxy server implementation in Go with flexible authentication and multi-platform support.

Features

🚀 SOCKS5 Protocol Support - Full SOCKS5 proxy implementation
🔐 Flexible Authentication - File-based and command-line user management
🐳 Docker Ready - Multi-architecture Docker images (amd64, arm64)
⚙️ Command Line Interface - Rich CLI with multiple configuration options
🌍 Multi-Platform Linux - Binaries for Linux (amd64, arm64, arm)
📦 No Authentication Mode - Optional anonymous access
🔄 Auto-Releases - Automated GitHub Actions for building and releasing
🛡️ Secure - Support for multiple users with different passwords
📝 Systemd Service - Easy system service integration

Installation

Option 1: Download Pre-built Binaries

Download the latest release for your platform from GitHub Releases:

Linux (64-bit): go-socks5-proxy-linux-amd64.tar.gz
Linux (ARM64): go-socks5-proxy-linux-arm64.tar.gz
Linux (ARM 32-bit): go-socks5-proxy-linux-arm.tar.gz

# Download and extract (example for Linux amd64)
wget https://github.com/ariadata/go-socks5-proxy/releases/latest/download/go-socks5-proxy-linux-amd64.tar.gz
tar -xzf go-socks5-proxy-linux-amd64.tar.gz
chmod +x go-socks5-proxy-linux-amd64

Option 2: Using Docker

# Pull the latest image
docker pull ghcr.io/ariadata/go-socks5-proxy:latest

# Run with Docker
docker run -d -p 1080:1080 \
  -v $(pwd)/users.conf:/app/users.conf \
  --name socks5-proxy \
  ghcr.io/ariadata/go-socks5-proxy:latest

Option 3: Build from Source

git clone https://github.com/ariadata/go-socks5-proxy.git
cd go-socks5-proxy
go build -o socks5-server main.go

Usage

Command Line Options

./socks5-server [OPTIONS]

Available Options:

--host HOST - Host to bind to (default: 0.0.0.0)
--port PORT - Port to listen on (default: 1080)
--users FILE - Path to users configuration file
--user USER - User credentials in format username:password (can be used multiple times)
--version - Show version information
--help - Show help message

Authentication Modes

1. No Authentication (Anonymous Access)

./socks5-server --port 1080

2. File-based Authentication

Create a users.conf file:

# SOCKS5 Proxy User Configuration
# Format: username:password
# Lines starting with # are comments

user1:secure_password_123
user2:another_secure_password
admin:very_secure_admin_password

Run with file authentication:

./socks5-server --users users.conf --port 1080

3. Command-line Authentication

./socks5-server --user "user1:pass1" --user "user2:pass2" --port 1080

4. Mixed Authentication (File + Command-line)

./socks5-server --users users.conf --user "extrauser:extrapass" --port 1080

Environment Variables

You can also configure the server using environment variables:

SOCKS5_PORT - Port to listen on (default: :1080)
SOCKS5_CONFIG - Path to users configuration file

export SOCKS5_PORT=":8080"
export SOCKS5_CONFIG="/etc/socks5/users.conf"
./socks5-server

Systemd Service Setup

Create a systemd service for automatic startup:

# Copy binary to system location
sudo cp socks5-server /usr/local/bin/
sudo chmod +x /usr/local/bin/socks5-server

# Create users configuration
sudo mkdir -p /etc/socks5
sudo cp users.conf /etc/socks5/

# Create systemd service
sudo tee /etc/systemd/system/socks5-server.service > /dev/null << 'EOF'
[Unit]
Description=SOCKS5 Proxy Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/socks5-server --users /etc/socks5/users.conf --port 1080
Restart=always
RestartSec=5
User=nobody
Group=nogroup
WorkingDirectory=/etc/socks5

[Install]
WantedBy=multi-user.target
EOF

# Enable and start the service
sudo systemctl daemon-reload
sudo systemctl enable socks5-server
sudo systemctl start socks5-server

# Check status
sudo systemctl status socks5-server

Docker Deployment

Using Docker Run

# With authentication
docker run -d \
  --name socks5-proxy \
  -p 1080:1080 \
  -v $(pwd)/users.conf:/app/users.conf \
  --restart unless-stopped \
  ghcr.io/ariadata/go-socks5-proxy:latest

# Without authentication (anonymous access)
docker run -d \
  --name socks5-proxy \
  -p 1080:1080 \
  --restart unless-stopped \
  ghcr.io/ariadata/go-socks5-proxy:latest

Using Docker Compose

Create docker-compose.yml:

version: "3.8"
services:
  socks5-proxy:
    image: ghcr.io/ariadata/go-socks5-proxy:latest
    container_name: socks5-proxy
    restart: unless-stopped
    ports:
      - "1080:1080"
    volumes:
      - ./users.conf:/app/users.conf
    # Optional: Override default command
    # command: ["./socks5-server", "--users", "/app/users.conf", "--port", "1080"]

Start the service:

docker-compose up -d

Testing the Proxy

Using curl

# Test with authentication
curl -x socks5://username:password@127.0.0.1:1080 https://httpbin.org/ip

# Test without authentication (if running in anonymous mode)
curl -x socks5://127.0.0.1:1080 https://httpbin.org/ip

# Test SOCKS5h (hostname resolution through proxy)
curl -x socks5h://username:password@127.0.0.1:1080 https://httpbin.org/ip

Using Browser

Configure your browser's SOCKS5 proxy settings:

Proxy Type: SOCKS5
Host: 127.0.0.1 (or your server IP)
Port: 1080
Username/Password: As configured

Configuration Examples

High Security Setup

# Create secure users file with strong passwords
echo "admin:$(openssl rand -base64 32)" > users.conf
echo "user1:$(openssl rand -base64 32)" >> users.conf

# Set secure file permissions
chmod 600 users.conf

# Run server
./socks5-server --users users.conf --host 127.0.0.1 --port 1080

Multi-User Corporate Setup

# users.conf
admin:AdminSecurePass123!
sales_team:SalesPass456@
dev_team:DevSecurePass789#
guest:GuestTempPass000$

# Run server
./socks5-server --users users.conf --port 1080

Development & Building

GitHub Actions Workflows

This project includes automated workflows:

Docker Build (build.yml) - Builds and pushes Docker images to GHCR on every push to main
Linux Multi-Platform Release (release-multiplatform.yml) - Creates Linux binaries for all architectures on release

Manual Building

# Build for current platform
go build -o socks5-server main.go

# Cross-compile for different platforms
GOOS=linux GOARCH=amd64 go build -o socks5-server-linux-amd64 main.go
GOOS=linux GOARCH=arm64 go build -o socks5-server-linux-arm64 main.go

Security Considerations

Strong Passwords - Use complex passwords (minimum 12 characters)
File Permissions - Set users.conf to 600 (chmod 600 users.conf)
Network Security - Use firewall rules to restrict access
Regular Updates - Keep the proxy server updated
Monitoring - Monitor logs for suspicious activity
User Management - Regularly rotate credentials

Troubleshooting

Common Issues

Connection Refused

# Check if server is running
netstat -tlnp | grep 1080

# Check logs
journalctl -u socks5-server -f

Authentication Failed
- Verify credentials in users.conf
- Check file permissions
- Ensure no extra spaces in username:password format

Docker Issues

# Check container logs
docker logs socks5-proxy

# Check if users.conf is mounted correctly
docker exec socks5-proxy ls -la /app/

Logs and Monitoring

# View systemd service logs
sudo journalctl -u socks5-server -f

# View Docker container logs
docker logs -f socks5-proxy

# Check service status
sudo systemctl status socks5-server

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

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

Support

📖 Documentation: Check this README and inline help (--help)
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions

Acknowledgments

Built with go-socks5 library
Inspired by the need for a simple, secure SOCKS5 proxy solution

Name	Name	Last commit message	Last commit date
Latest commit History 27 Commits 27 Commits
.github/workflows	.github/workflows
.idea	.idea
Dockerfile	Dockerfile
README.md	README.md
docker-compose.yml	docker-compose.yml
go.mod	go.mod
go.sum	go.sum
main.go	main.go
main_test.go	main_test.go
users.conf	users.conf

Search code, repositories, users, issues, pull requests...

Folders and files

Latest commit

History

Repository files navigation

Go SOCKS5 Proxy Server

Features

Installation

Option 1: Download Pre-built Binaries

Option 2: Using Docker

Option 3: Build from Source

Usage

Command Line Options

Authentication Modes

1. No Authentication (Anonymous Access)

2. File-based Authentication

3. Command-line Authentication

4. Mixed Authentication (File + Command-line)

Environment Variables

Systemd Service Setup

Docker Deployment

Using Docker Run

Using Docker Compose

Testing the Proxy

Using curl

Using Browser

Configuration Examples

High Security Setup

Multi-User Corporate Setup

Development & Building

GitHub Actions Workflows

Manual Building

Security Considerations

Troubleshooting

Common Issues

Logs and Monitoring

Contributing

License

Support

Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Uh oh!

Contributors 1

Languages

Packages