mirror of https://github.com/bol-van/zapret/
Cursor Agent
11 months ago
7 changed files with 476 additions and 108 deletions
@ -0,0 +1,275 @@ |
|||
# 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)** |
|||
```bash |
|||
# Wrong: Treating macOS as BSD |
|||
CFLAGS_BSD = -Wno-address-of-packed-member |
|||
$(CC) $(CFLAGS) $(CFLAGS_BSD) -o binary source.c |
|||
``` |
|||
|
|||
#### **After (Correct)** |
|||
```bash |
|||
# 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** |
|||
```bash |
|||
systemctl start zapret |
|||
systemctl status zapret |
|||
``` |
|||
|
|||
#### **BSD** |
|||
```bash |
|||
service zapret start |
|||
service zapret status |
|||
``` |
|||
|
|||
#### **macOS** |
|||
```bash |
|||
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** |
|||
```bash |
|||
# Test on actual macOS |
|||
./scripts/test_macos_arch.sh |
|||
make mac |
|||
sudo /opt/zapret/init.d/macos/zapret start |
|||
``` |
|||
|
|||
#### **BSD Testing** |
|||
```bash |
|||
# 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** |
|||
```bash |
|||
# "macOS is BSD, so this will work" |
|||
if [ "$(uname)" = "Darwin" ]; then |
|||
# Use BSD-specific code |
|||
make bsd |
|||
fi |
|||
``` |
|||
|
|||
#### **Correct Approach** |
|||
```bash |
|||
# "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** |
|||
```bash |
|||
# Using BSD flags on macOS |
|||
CFLAGS_BSD = -DBSD |
|||
$(CC) $(CFLAGS_BSD) -o binary source.c |
|||
``` |
|||
|
|||
#### **Correct Flags** |
|||
```bash |
|||
# Using macOS-specific flags |
|||
CFLAGS_MACOS = -DMACOS_DARWIN |
|||
$(CC) $(CFLAGS_MACOS) -o binary source.c |
|||
``` |
|||
|
|||
### **3. Runtime Errors** |
|||
|
|||
#### **Wrong Service Management** |
|||
```bash |
|||
# Trying to use BSD service commands on macOS |
|||
service zapret start # This won't work |
|||
``` |
|||
|
|||
#### **Correct Service Management** |
|||
```bash |
|||
# 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](https://developer.apple.com/documentation/) |
|||
- [macOS System Architecture](https://developer.apple.com/library/archive/documentation/Darwin/Conceptual/KernelProgramming/Architecture/Architecture.html) |
|||
- [XNU Kernel Source](https://github.com/apple/darwin-xnu) |
|||
|
|||
### **BSD Documentation** |
|||
- [FreeBSD Handbook](https://docs.freebsd.org/en/books/handbook/) |
|||
- [OpenBSD Documentation](https://www.openbsd.org/faq/) |
|||
- [NetBSD Documentation](https://netbsd.org/docs/) |
|||
|
|||
### **zapret-Specific** |
|||
- [README_MACOS_FINAL.md](../README_MACOS_FINAL.md) |
|||
- [CHANGELOG_MACOS_COMPLETE.md](../CHANGELOG_MACOS_COMPLETE.md) |
|||
- [Installation Guide](../install_macos.sh) |
|||
|
|||
--- |
|||
|
|||
## 🎯 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. |
|||
Loading…
Reference in new issue