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