Skip to content

Macos v1.1 porting (please ignore the version in branch name)#35

Open
PouriaCh wants to merge 9 commits intoSamNet-dev:macos-editionfrom
PouriaCh:macos-v1.2-porting
Open

Macos v1.1 porting (please ignore the version in branch name)#35
PouriaCh wants to merge 9 commits intoSamNet-dev:macos-editionfrom
PouriaCh:macos-v1.2-porting

Conversation

@PouriaCh
Copy link

@PouriaCh PouriaCh commented Feb 7, 2026 •
edited
Loading

Conduit Manager v1.1 - macOS Edition

Summary

This PR introduces v1.1 of Conduit Manager for macOS, bringing feature parity with the Linux edition while implementing macOS-specific optimizations. The implementation eliminates the need for sudo/tcpdump through innovative use of Docker container inspection via /proc/net/tcp.

Key Features

✅ Multi-Container Support

  • Scale from 1 to 32 Conduit containers based on hardware capacity
  • Per-container configuration (max-clients, bandwidth, CPU, memory limits)
  • Individual container management via CLI and Telegram bot
  • Dynamic container detection and automatic settings synchronization

✅ Background Tracker Service

  • 24/7 network monitoring with country-level GeoIP statistics
  • Real-time IP extraction via Docker /proc/net/tcp inspection (no sudo required)
  • Cumulative traffic tracking and lifetime IP statistics
  • Automatic file ownership management to prevent permission issues
  • 60-second update interval (optimized for accuracy and performance)

✅ Telegram Bot Integration

  • Automated periodic reports (configurable: 1h, 3h, 6h, 12h, 24h)
  • Real-time alerts: high CPU (>90%), high RAM (>90%), container down
  • Daily and weekly summaries (optional)
  • Custom server labels for multi-server setups

Remote Management Commands:

  • /status — Full status report with active clients and top upload countries
  • /peers — Show connected & connecting clients (now working on macOS)
  • /uptime — Per-container uptime and 24h availability
  • /containers — List all containers with detailed stats
  • /restart_N, /stop_N, /start_N — Container management

✅ Live Dashboard & Status Display

  • Real-time monitoring with 5-second refresh
  • Per-country traffic breakdown (TOP 5 active clients, TOP 5 by upload)
  • Side-by-side display matching Linux edition format
  • Resource usage: CPU (per-core and vCPU), RAM, network throughput

✅ Live Peers by Country (Interactive Map)

  • Full-screen display showing TOP 10 countries by traffic
  • Real-time active client counts per country
  • Cumulative upload/download traffic with percentage bars
  • 5-second refresh with synchronized progress bar countdown
  • No sudo required (uses Docker container inspection)

macOS-Specific Optimizations

Technical Implementation

1. Docker /proc/net/tcp Inspection (Eliminates sudo/tcpdump)

  • Direct read of active TCP connections from within Docker containers
  • Hex IP address conversion to decimal format (little-endian)
  • Private IP filtering (10.x, 172.16-31.x, 192.168.x, 127.x)
  • GeoIP lookup with automatic database path resolution
  • Result: Full tracker and Live Map functionality without root privileges

2. Modern Bash via Homebrew

  • Automatic installation of bash 5.x for associative array support
  • Explicit shebang (#!/opt/homebrew/bin/bash) in generated scripts
  • Required for country-level data aggregation in tracker
  • Ensures compatibility across macOS versions

3. File Ownership Management

  • fix_file_ownership() helper ensures proper permissions
  • Handles cases where scripts run with sudo
  • Prevents permission errors in background services (tracker, telegram)
  • Applies to all persistent data files

4. macOS Command Compatibility

  • Removed timeout command dependency (not available by default on macOS)
  • Fixed grep patterns for Docker STATS logs: grep "\[STATS\]" (with brackets)
  • Proper nohup usage with explicit bash interpreter path
  • Robust Docker binary resolution without blocking operations

Bug Fixes from Initial PR

Critical Fixes

  • ✅ Fixed Docker logs parsing: changed grep "STATS" to grep "\[STATS\]"
  • ✅ Removed timeout command causing hangs on macOS (not in default PATH)
  • ✅ Fixed tracker not sourcing settings.conf (container count was defaulting to 1)
  • ✅ Fixed tracker using wrong bash version (macOS bash 3.2 doesn't support associative arrays)
  • ✅ Fixed GeoIP database path resolution for macOS Homebrew installations
  • ✅ Fixed file ownership issues when running commands with sudo

Telegram Bot Fixes

  • ✅ Fixed /containers command showing "No stats available yet"
  • ✅ Fixed /peers command (now working on macOS via Docker inspection)
  • ✅ Re-enabled /peers in command list (was incorrectly disabled for macOS)
  • ✅ Fixed duplicate telegram_notify processes causing conflicts

UI/UX Fixes

  • ✅ Fixed Live Map countdown sync and progress bar animation (now 5 seconds)
  • ✅ Fixed status dashboard showing "fix_file_ownership: command not found"
  • ✅ Removed trailing ║ characters from Live Map header text lines
  • ✅ Fixed speed column in Live Map (removed due to tracker update frequency)
  • ✅ Added "[q] Back" to Live Map header for consistency with Linux
  • ✅ Fixed status dashboard exit delay for better responsiveness

Testing Performed

Comprehensive testing on macOS with Apple Silicon (M4):

  • ✅ Multi-container deployment (1, 2, 3+ containers tested)
  • ✅ Background tracker capturing IPs and GeoIP data without sudo
  • ✅ All Telegram bot commands: /status, /peers, /uptime, /containers, /restart_N, /stop_N, /start_N
  • ✅ Live dashboard refresh and per-country statistics display
  • ✅ Live Peers by Country map (option 11) - no sudo required
  • ✅ File ownership persistence across sudo/non-sudo runs
  • ✅ Container management via Telegram (start/stop/restart)
  • ✅ Resource usage monitoring (CPU per-core + vCPU, RAM, network)
  • ✅ GeoIP lookups with Iranian and international IPs
  • ✅ Telegram service stability (no duplicate processes)

Documentation Updates

README.md

  • ✅ Updated feature list to reflect "no sudo required"
  • ✅ Added /peers to Telegram bot commands
  • ✅ Updated "What's New" to highlight Docker /proc/net/tcp optimization
  • ✅ Removed mentions of tcpdump/sudo requirements
  • ✅ Added technical implementation details section
  • ✅ Removed "Known Limitations" section (resolved)

Code Comments

  • ✅ Documented hex IP conversion logic
  • ✅ Explained file ownership management approach
  • ✅ Added inline documentation for tracker data flow

Platform Differences (macOS vs Linux)

Feature Linux macOS Notes
Docker Docker Engine Docker Desktop Auto-installed via Homebrew
Network --network=host Port publishing (-p) Required for macOS
Services systemd nohup Background tracker & telegram
Auto-start systemd unit Not implemented Manual start after reboot
Peer tracking tcpdump Docker /proc/net/tcp No sudo needed on macOS
Bash version Default (4.x+) Homebrew (5.x) For associative arrays

Version Information

Current: v1.1.0-Mac
Target Branch: macos-edition (upstream)
Base Branch: macos-v1.2-porting (development)

This release achieves feature parity with the Linux v1.1 edition while optimizing for macOS platform constraints.

Breaking Changes

None. This is purely additive. Existing v1.0.2 macOS installations will seamlessly upgrade to v1.1.

Future Work (v1.2+)

Planned enhancements for future releases:

  • Container Management submenu (dedicated UI)
  • Settings & Tools submenu (better organization)
  • Advanced Stats menu (auto-refreshing breakdowns)
  • Info & Help submenu (documentation)
  • Peak/Average/History tracking
  • Data usage cap feature
  • CPU temperature display (macOS sysctl adaptation)
  • Tracker auto-regeneration on updates

Ready for merge - All features tested and working on macOS Apple Silicon.

PouriaCh and others added 6 commits February 6, 2026 02:50
@PouriaCh
Port macOS multi-container and stats parity features.
5567e58 
Adds multi-container support with per-container settings, dashboards, and syncs settings from running containers to keep status consistent. Also ports connection history/peak tracking and improves macOS system CPU + node ID handling.
@PouriaCh @cursoragent
Add background tracker on macOS.
f0fbc32 
Adds tracker script generation, toggle command, and auto-start after install/settings changes. Persists tracker settings and PID/log paths for consistent history collection.

Co-authored-by: Cursor <cursoragent@cursor.com>
@PouriaCh @cursoragent
Disable zero-peers alert on macOS in Telegram notifications
7f93872 
The zero-peers alert generates false positives on macOS because the
background notifier (running via nohup) cannot reliably get peer counts
from docker logs. This is the same root cause as the /peers and
/containers commands showing 0/0 or "No stats available yet".

Changes:
- Skip zero-peers alert entirely on macOS (OS check in notifier)
- Remove /peers command from Telegram help and test messages on macOS
- Update README to document zero-peers alert is disabled on macOS
- Other alerts (CPU, RAM, down) continue to work normally

This prevents users from receiving continuous "Zero peers for 2+ hours"
alerts when they actually have 100+ connected peers.

Co-authored-by: Cursor <cursoragent@cursor.com>
@PouriaCh @cursoragent
Fix extra newline in Telegram test message on macOS
bc72207 
Remove trailing newline after conditional /peers command to prevent
blank line between /status and /uptime in the Available Commands list.

Co-authored-by: Cursor <cursoragent@cursor.com>
@PouriaCh
update version
d32c120
@PouriaCh
update README.md
199ccda
@PouriaCh
Copy link
Author

PouriaCh commented Feb 7, 2026

Hi @SamNet-dev. This PR is for v1.1-Mac. I started breaking down the features from v1.2 tag and porting them in smaller pieces into macos. Still 3000 lines of code is too much, but it would get smaller as it gets closer to the main branch :)

My goal in this PR is not necessarily match the branch v1.1 tag. It's just a step towards achieving parity. Hope that makes sense.

Please let me know if there is anything missing. Thanks.

@PouriaCh PouriaCh marked this pull request as draft February 8, 2026 03:38
PouriaCh and others added 2 commits February 8, 2026 00:37
@PouriaCh @cursoragent
Fix tracker and GeoIP for macOS without sudo dependency
2764798 
Major improvements to tracker functionality on macOS:

- **Remove tcpdump/sudo requirement**: Rewrite tracker to use Docker's
  /proc/net/tcp inspection for IP extraction (no sudo needed)
- **Fix GeoIP database detection**: Auto-detect database in multiple
  paths including ~/.conduit/geoip/ directory
- **Fix bash compatibility**: Use Homebrew bash for associative arrays
  (macOS system bash 3.2 doesn't support them)
- **Add file ownership fixes**: Prevent permission issues when running
  commands with sudo by auto-correcting ownership to SUDO_USER
- **Update Live Map**: Show informative message on macOS directing users
  to working alternatives (Telegram /status, Dashboard)

Technical changes:
- Tracker shebang: #!/bin/bash → #!/opt/homebrew/bin/bash
- IP extraction: tcpdump → docker exec <container> cat /proc/net/tcp
- GeoIP path: hardcoded → multi-path detection with fallback
- Added fix_file_ownership() helper throughout tracker/telegram scripts
- Load settings.conf in tracker for proper CONTAINER_COUNT detection

Telegram reports now show accurate country breakdown:
- 📡 Total served with proper traffic tracking
- 👤 Total lifetime IPs served (actual count)
- 🗺 Top by peers (United States, Canada, etc.)
- 🌍 Top by upload (percentage per country)

Co-authored-by: Cursor <cursoragent@cursor.com>
@PouriaCh @cursoragent
Add Live Peer Map for macOS using tracker data
5f3bc5f 
Implement show_peers_macos() to display live peer traffic by country
without requiring sudo/tcpdump:

- **Reads from tracker data**: Uses background tracker's cumulative_data
  and tracker_snapshot files instead of real-time packet capture
- **Display format**: Matches Linux version with TOP 10 countries by
  traffic (FROM/TO) and active client counts
- **Auto-refresh**: Display refreshes every 5s, tracker updates every 60s
- **No privileges needed**: Works without sudo by leveraging existing
  tracker infrastructure

Display shows:
- 📥 TOP 10 TRAFFIC FROM (download from peers)
- 📤 TOP 10 TRAFFIC TO (upload to peers)
- Country name, total traffic, and active client count per country
- Live update timestamp with [LIVE] indicator
- Clear exit instructions: "Press any key to exit"

This completes feature parity with Linux for peer traffic visualization
on macOS without requiring elevated privileges.

Co-authored-by: Cursor <cursoragent@cursor.com>
@PouriaCh PouriaCh marked this pull request as ready for review February 8, 2026 07:40
@SamNet-dev
Copy link
Owner

SamNet-dev commented Feb 8, 2026 •
edited
Loading

Hi @PouriaCh , thanks for putting up with this and updating. I will take a look as soon as I get a chance. Thank you again. You just make sure it's all good to go, and there are no bugs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@PouriaCh @SamNet-dev