zapret/README_MACOS_ENHANCED.md

Enhanced MacOS Support for zapret

🎯 Overview

This document describes the enhanced MacOS support for the zapret DPI circumvention tool. The project has been significantly improved to work seamlessly on both Intel (x86_64) and Apple Silicon (ARM64) MacOS systems.

✨ Key Improvements

1. Automatic Architecture Detection

• Automatically detects Intel vs Apple Silicon
• Sets appropriate compilation targets
• No manual configuration required
• Supports MacOS versions 10.8+ (Mountain Lion to Sonoma)

2. Enhanced Build System

• New make mac target for current architecture
• New make mac-universal target for universal binaries
• New make mac-auto target for auto-detection
• New make mac-info target for build information
• Environment variable support (MACOS_TARGET, MACOS_VERSION)

3. Improved Component Support

• tpws: Full support for MacOS (recommended for DPI bypass)
• ip2net: Full support for MacOS
• mdig: Full support for MacOS
• nfq: Limited support (no NFQUEUE on MacOS, builds dvtws instead)

4. New Installation Scripts

• install_macos.sh: Dedicated MacOS installer
• scripts/macos_arch_detect.sh: Enhanced architecture management
• scripts/test_macos_arch.sh: Comprehensive system testing

🚀 Quick Start

1. Clone and Navigate

git clone <repository-url>
cd zapret

2. Test Your System

# Test architecture detection
./scripts/test_macos_arch.sh

# Check system readiness
./scripts/macos_arch_detect.sh check

3. Build and Install

# Option 1: Use the new MacOS installer (recommended)
./install_macos.sh full

# Option 2: Manual build and install
make mac
sudo ./install_macos.sh install

🛠️ Build Targets

Single Architecture

# Build for current architecture (automatic detection)
make mac

# Build for specific architecture
MACOS_TARGET="arm64-apple-macos11.0" make mac
MACOS_TARGET="x86_64-apple-macos12.0" make mac

Universal Binary

# Build universal binary (x86_64 + arm64)
make mac-universal

Special Targets

# Auto-detect and build
make mac-auto

# Show build information
make mac-info

# Clean MacOS builds only
make mac-clean

📱 Supported MacOS Versions

Version	Codename	Support Level	Notes
10.8+	Mountain Lion	✅ Full	Minimum supported version
11.0+	Big Sur	✅ Full	Recommended minimum
12.0+	Monterey	✅ Full	Full support
13.0+	Ventura	✅ Full	Full support
14.0+	Sonoma	✅ Full	Latest version

🔧 Architecture Support

Intel (x86_64)

• Target: x86_64-apple-macos<version>
• Optimization: Native Intel performance
• Compatibility: All Intel Macs

Apple Silicon (ARM64)

• Target: arm64-apple-macos<version>
• Optimization: Native ARM64 performance
• Compatibility: M1, M2, M3, and future Apple Silicon

Universal Binary

• Target: Both architectures in single binary
• Size: Larger than single-architecture builds
• Compatibility: Works on all supported Macs

📋 Requirements

Minimum Requirements

• OS: macOS 10.8 (Mountain Lion) or later
• Architecture: Intel (x86_64) or Apple Silicon (ARM64)
• RAM: 4GB (8GB recommended)
• Storage: 2GB free space

Build Tools

• Xcode Command Line Tools (automatically installed if missing)
• make: Build system
• cc/clang: C compiler
• lipo: Universal binary creation
• strip: Binary optimization

🧪 Testing

System Verification

# Comprehensive system test
./scripts/test_macos_arch.sh

# Architecture detection
./scripts/macos_arch_detect.sh detect

# System information
./scripts/macos_arch_detect.sh info

# Build readiness check
./scripts/macos_arch_detect.sh check

Build Testing

# Test single architecture build
make mac

# Test universal binary build
make mac-universal

# Test specific version build
./scripts/macos_arch_detect.sh version 12.0

📚 Usage Examples

Basic Usage

# Start tpws service
sudo /opt/zapret/init.d/macos/zapret start

# Check status
sudo /opt/zapret/init.d/macos/zapret status

# Stop service
sudo /opt/zapret/init.d/macos/zapret stop

Advanced Usage

# Start only daemons (no firewall)
sudo /opt/zapret/init.d/macos/zapret start-daemons

# Start only firewall
sudo /opt/zapret/init.d/macos/zapret start-fw

# Reload firewall tables
sudo /opt/zapret/init.d/macos/zapret reload-fw-tables

Manual tpws Usage

# Transparent proxy mode
sudo /opt/zapret/tpws --port=988 --bind-addr=127.0.0.1

# SOCKS proxy mode
/opt/zapret/tpws --socks --port=987 --bind-addr=127.0.0.1

🔒 Security Considerations

System Integrity Protection (SIP)

• SIP may affect some operations
• Check status: csrutil status
• Disable if needed (not recommended for security)

Firewall Configuration

• Uses PF (Packet Filter) on MacOS
• Automatically patches /etc/pf.conf
• Creates anchors in /etc/pf.anchors

Permissions

• Binaries installed as root:wheel
• Service runs with appropriate permissions
• Configuration files properly secured

🆘 Troubleshooting

Common Issues

1. "Command not found: make"

# Install Xcode Command Line Tools
xcode-select --install

2. "Permission denied"

# Make scripts executable
chmod +x scripts/*.sh
chmod +x install_macos.sh

3. "Architecture mismatch"

# Clean and rebuild
make mac-clean
make mac

4. "Build failed"

# Check system requirements
./scripts/macos_arch_detect.sh check

# Verify build tools
./scripts/macos_arch_detect.sh info

Build Errors

Compiler Issues

# Check compiler
which cc
which clang

# Reinstall Xcode Command Line Tools
sudo rm -rf /Library/Developer/CommandLineTools
xcode-select --install

Library Issues

# Check for required libraries
otool -L binaries/my/tpws

# Verify epoll-shim installation
ls -la tpws/epoll-shim/

📖 Documentation

Primary Documentation

• This file: Enhanced MacOS support guide
• README_MACOS_REFACTORING.md: Technical refactoring details
• QUICK_START_MACOS.md: Quick start guide
• CHANGELOG_MACOS_REFACTORING.md: Detailed changes

Component Documentation

• docs/bsd.en.md: BSD/MacOS specific information
• docs/readme.en.md: General project documentation

Script Documentation

• scripts/macos_arch_detect.sh --help: Architecture script help
• install_macos.sh --help: Installer script help

🔮 Future Plans

Planned Improvements

• Support for newer MacOS versions (15.0+)
• Performance benchmarking tools
• Cross-compilation from Linux
• Automated architecture testing
• Homebrew package support

Known Limitations

• nfq component: Limited functionality (no NFQUEUE)
• Internet sharing: May interfere with tpws
• SIP: May require temporary disable for some operations

🤝 Contributing

Development Guidelines

1. Test on both Intel and Apple Silicon
2. Verify compatibility with multiple MacOS versions
3. Use the enhanced build system
4. Follow MacOS-specific best practices

Testing Checklist

• Intel MacOS 11.0+
• Apple Silicon MacOS 11.0+
• Universal binary compilation
• Service installation and management
• Firewall configuration

📞 Support

Getting Help

1. Check documentation: Start with this file
2. Run diagnostics: ./scripts/test_macos_arch.sh
3. Check system: ./scripts/macos_arch_detect.sh info
4. Review logs: Check system logs for errors

Reporting Issues

• Include MacOS version and architecture
• Run diagnostic scripts and include output
• Provide build logs if compilation fails
• Mention any custom configuration

Community Resources

• GitHub Issues: For bug reports and feature requests
• Documentation: Comprehensive guides and examples
• Scripts: Automated testing and management tools

---

🎉 Status

Current Status: ✅ Production Ready
Compatibility: MacOS 10.8+ (Mountain Lion to Sonoma)
Architectures: x86_64, arm64, Universal
Components: tpws ✅, ip2net ✅, mdig ✅, nfq ⚠️

The enhanced MacOS support is complete and ready for production use. All changes are backward compatible and existing installations will continue to work without modification.