zapret/docs/MACOS_VS_BSD.md

macOS vs BSD: Understanding the Differences

🎯 Overview

This document explains the critical differences between macOS and BSD systems. While macOS has some BSD-like elements, it is NOT BSD and should not be treated as such.

🔍 Key Differences

1. Kernel Architecture

macOS (Darwin)

• Kernel: XNU (X is Not Unix)
• Architecture: Hybrid kernel combining:
  • Mach microkernel (from Carnegie Mellon University)
  • BSD-like layer (FreeBSD 4.4 derived)
  • Apple-specific components (I/O Kit, networking stack)
• Type: Hybrid microkernel

BSD (FreeBSD, OpenBSD, NetBSD)

• Kernel: Monolithic BSD kernel
• Architecture: Traditional Unix-like kernel
• Type: Monolithic kernel

2. System Calls and APIs

macOS

• System calls: Mach system calls + BSD compatibility layer
• Networking: Apple-modified BSD networking stack
• File system: HFS+, APFS (Apple-specific)
• Security: SIP, code signing, entitlements

BSD

• System calls: Traditional BSD system calls
• Networking: Standard BSD networking stack
• File system: UFS, ZFS, etc.
• Security: Traditional Unix security model

3. Networking Stack

macOS

• Firewall: PF (Packet Filter) with Apple modifications
• Network interfaces: Apple-specific naming and behavior
• IPv6: Modified IPv6 implementation
• Divert sockets: Limited support, different behavior

BSD

• Firewall: PF, ipfw, IPFilter
• Network interfaces: Standard BSD naming
• IPv6: Standard BSD IPv6 implementation
• Divert sockets: Full support, standard behavior

🚨 Why This Matters for zapret

1. Compilation Differences

Before (Incorrect)

# Wrong: Treating macOS as BSD
CFLAGS_BSD = -Wno-address-of-packed-member
$(CC) $(CFLAGS) $(CFLAGS_BSD) -o binary source.c

After (Correct)

# Correct: macOS-specific flags
CFLAGS_MACOS = -Wno-address-of-packed-member -DMACOS_DARWIN
$(CC) $(CFLAGS) $(CFLAGS_MACOS) -o binary source.c

2. Component Support

nfq Component

• Linux: Full NFQUEUE support
• BSD: Divert socket support
• macOS: Limited divert socket support (different behavior)

tpws Component

• Linux: epoll support
• BSD: kqueue support
• macOS: epoll-shim (emulation layer)

3. Service Management

Linux

systemctl start zapret
systemctl status zapret

BSD

service zapret start
service zapret status

macOS

sudo /opt/zapret/init.d/macos/zapret start
sudo launchctl load /Library/LaunchDaemons/zapret.plist

🔧 Technical Implications

1. Build System

macOS-Specific Requirements

• Compiler flags: -DMACOS_DARWIN
• Target specification: -target $(MACOS_TARGET)
• Version targeting: -mmacosx-version-min=$(MACOS_VERSION)
• Libraries: macOS-specific library paths

BSD Requirements

• Compiler flags: -DBSD
• Target specification: Standard BSD targets
• Version targeting: BSD version-specific
• Libraries: Standard BSD library paths

2. Runtime Behavior

macOS

• Process management: launchd
• Firewall rules: PF with Apple modifications
• Security: SIP, code signing
• Networking: Apple-modified stack

BSD

• Process management: rc system
• Firewall rules: Standard PF/ipfw
• Security: Traditional Unix model
• Networking: Standard BSD stack

📚 Best Practices

1. Development

Do's

• ✅ Use CFLAGS_MACOS for macOS-specific compilation
• ✅ Define MACOS_DARWIN macro
• ✅ Test on actual macOS systems
• ✅ Use macOS-specific APIs when available

Don'ts

• ❌ Don't assume macOS is BSD
• ❌ Don't use BSD-specific code without testing
• ❌ Don't ignore macOS-specific security features
• ❌ Don't assume BSD networking behavior

2. Testing

macOS Testing

# Test on actual macOS
./scripts/test_macos_arch.sh
make mac
sudo /opt/zapret/init.d/macos/zapret start

BSD Testing

# Test on actual BSD
make bsd
sudo service zapret start

3. Documentation

Clear Labeling

• Label: "macOS (Darwin)" not "BSD"
• Explain: Hybrid system characteristics
• Warn: About compatibility limitations
• Guide: macOS-specific usage

🆘 Common Mistakes

1. Assumption Errors

Wrong Assumption

# "macOS is BSD, so this will work"
if [ "$(uname)" = "Darwin" ]; then
    # Use BSD-specific code
    make bsd
fi

Correct Approach

# "macOS is a hybrid system, use macOS-specific code"
if [ "$(uname)" = "Darwin" ]; then
    # Use macOS-specific code
    make mac
fi

2. Compilation Errors

Wrong Flags

# Using BSD flags on macOS
CFLAGS_BSD = -DBSD
$(CC) $(CFLAGS_BSD) -o binary source.c

Correct Flags

# Using macOS-specific flags
CFLAGS_MACOS = -DMACOS_DARWIN
$(CC) $(CFLAGS_MACOS) -o binary source.c

3. Runtime Errors

Wrong Service Management

# Trying to use BSD service commands on macOS
service zapret start  # This won't work

Correct Service Management

# Using macOS-specific service management
sudo /opt/zapret/init.d/macos/zapret start

🔮 Future Considerations

1. macOS Evolution

• New versions: macOS 15.0+ support
• Architecture changes: Apple Silicon evolution
• Security features: Enhanced SIP, new entitlements
• Networking: Improved IPv6, new protocols

2. Compatibility Maintenance

• Version testing: Test on multiple macOS versions
• Architecture testing: Test on Intel and Apple Silicon
• Security testing: Test with SIP enabled/disabled
• Integration testing: Test with macOS updates

📖 References

macOS Documentation

• Apple Developer Documentation
• macOS System Architecture
• XNU Kernel Source

BSD Documentation

• FreeBSD Handbook
• OpenBSD Documentation
• NetBSD Documentation

zapret-Specific

• README_MACOS_FINAL.md
• CHANGELOG_MACOS_COMPLETE.md
• Installation Guide

---

🎯 Summary

macOS is NOT BSD - it's a hybrid system with:

• XNU kernel (Mach + BSD-like layer + Apple components)
• Unique networking stack and system calls
• Apple-specific security features (SIP, code signing)
• Different firewall (PF) and service management (launchd)
• Limited compatibility with BSD systems

When developing for macOS:

1. Use macOS-specific flags and macros
2. Test on actual macOS systems
3. Don't assume BSD compatibility
4. Follow macOS best practices
5. Document macOS-specific behavior

This understanding is crucial for proper zapret development and deployment on macOS systems.