{"id":19195420,"url":"https://github.com/ardupilot/udpproxy","last_synced_at":"2025-08-08T21:04:29.908Z","repository":{"id":142048284,"uuid":"595351965","full_name":"ArduPilot/UDPProxy","owner":"ArduPilot","description":"UDP Proxy For MAVLink2","archived":false,"fork":false,"pushed_at":"2025-07-31T03:50:07.000Z","size":88,"stargazers_count":8,"open_issues_count":1,"forks_count":6,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-07-31T06:41:12.218Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ArduPilot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-01-30T22:41:32.000Z","updated_at":"2025-07-31T03:50:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"840b450b-044a-4b79-b9da-353cae6e2d82","html_url":"https://github.com/ArduPilot/UDPProxy","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ArduPilot/UDPProxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArduPilot%2FUDPProxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArduPilot%2FUDPProxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArduPilot%2FUDPProxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArduPilot%2FUDPProxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ArduPilot","download_url":"https://codeload.github.com/ArduPilot/UDPProxy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArduPilot%2FUDPProxy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269489013,"owners_count":24425566,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-08T02:00:09.200Z","response_time":72,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T12:09:53.097Z","updated_at":"2025-08-08T21:04:29.900Z","avatar_url":"https://github.com/ArduPilot.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# UDP Proxy for MAVLink\n\nThis is a UDP/TCP/WebSocket Proxy for MAVLink to facilitate remote support of ArduPilot users.\n\nFor more information on using the support proxy see https://support.ardupilot.org\n\n## Features\n\n- Both support engineer and user can be on private networks\n- Supports many users running in parallel\n- Uses MAVLink2 signed connections from the support engineer\n- Uses normal UDP/TCP forwarding in users GCS\n- Supports both TCP and UDP, including mixed connections\n- Supports WebSocket and WebSocket+SSL TCP connections for both user\n  and support engineer\n- supports up to 8 simultaneous connections by support engineer\n\n## How It Works\n\n![UDPProxy Architecture](udpproxy-diagram.svg)\n\nUDPProxy acts as a bridge between ArduPilot users and support engineers:\n\n1. **User Side**: Connects their Ground Control Station to the proxy server (e.g., port 10001)\n2. **Proxy Server**: Routes traffic between user and engineer ports with authentication\n3. **Engineer Side**: Connects with MAVLink2 signed authentication (e.g., port 10002)\n\nThis allows both parties to be behind NAT/firewalls while maintaining\nsecure, authenticated connections.\n\nBoth sides can optionally use WebSocket+SSL to get a fully encrypted link.\n\n## Building\n\n### Prerequisites\n\n```bash\n# Ubuntu/Debian\nsudo apt install libtdb-dev python3-tdb python3-venv gcc g++ git libssl-dev\n\n```\n\n### Python Virtual Environment Setup\n\nIt's recommended to use a Python virtual environment to install pymavlink:\n\n```bash\n# Create a virtual environment\npython3 -m venv --system-site-packages venv\n\n# Activate the virtual environment\nsource venv/bin/activate\n\n# Install pymavlink in the virtual environment\npip install pymavlink\n```\n\n### Get the source\n\n```bash\n# Clone the repository\ngit clone https://github.com/ArduPilot/UDPProxy.git\ncd UDPProxy\n```\n\n### Building UDPProxy\n\n```bash\n# Build everything (initializes submodules, generates headers, compiles)\nmake\n\n# Or see all available options\nmake help\n```\n\n**Note: Remember to activate the virtual environment whenever you need to use pymavlink**\n\n## Configuration and Usage\n\n### Initial Setup\n\nUDPProxy should be run on a machine with a public IP address or through an internet domain. Initialize the database once:\n\n```bash\n# Initialize the key database\n./keydb.py initialise\n\n# Or with virtual environment\nsource venv/bin/activate\npython3 keydb.py initialise\n```\n\n### Adding Users\n\nAdd support engineer and user port pairs:\n\n```bash\n# Add a user: USER_PORT ENGINEER_PORT NAME PASSPHRASE\n./keydb.py add 10001 10002 'Support1' MySecurePassPhrase\n\n# Convention examples:\n# Even ports for users, odd for engineers:\n./keydb.py add 10004 10005 'Support2' AnotherPassPhrase\n\n# Or use port offsets:\n./keydb.py add 11001 21001 'Support3' ThirdPassPhrase\n```\n\n### Running the Proxy\n\n```bash\n# Start the proxy (runs in foreground)\n./udpproxy\n\n# Check if running in another terminal\npgrep udpproxy\n```\n\n### Supporting WebSocket + SSL\n\nTo support SSL encrypted links for WebSocket connections (both for\nuser connections and support engineer connections) you will need to\nprovide a fullchain.pem and privkey.pem file in the directory where\nyou start udpproxy. These files must be readable by udpproxy. SSL\nsupport has been tested with Let's Encrypt certificates. Note that\nwhen you renew your certificates you will need to update the files in\nthis directory, or use symlinks to the system certificates.\n\n### Automatic Startup\n\n#### The cron way\n\nFor production deployment, you can use cron for automatic startup and restart:\n\n```bash\n# Edit crontab\ncrontab -e\n\n# Add these lines:\n*/1 * * * * $HOME/UDPProxy/start_proxy.sh\n@reboot $HOME/UDPProxy/start_proxy.sh\n```\n\nThe `start_proxy.sh` script will:\n- Check if udpproxy is already running\n- Start it if not running\n- Log output to `proxy.log` and cron activity to `cron.log`\n\n### Monitoring\n\n```bash\n# Check proxy status\npgrep udpproxy\n\n# View logs\ntail -f proxy.log      # Proxy output\ntail -f cron.log       # Cron activity\n\n# List current users\n./keydb.py list\n\n# Check active connections\nnetstat -ln | grep \":1000[0-9]\"\n```\n\n## Docker Usage\n\nUDPProxy can also be run using Docker for easier deployment and management.\n\n### Building the Docker Image\n\n```bash\ndocker build -f docker/Dockerfile -t ap-udpproxy .\n```\n\n### Running with Docker\n\n```bash\n# Create a volume for persistent data (keys.tdb and logs)\ndocker volume create udpproxy-data\n\n# Initialize the database (first time only)\ndocker run --rm -v udpproxy-data:/app/data -it ap-udpproxy keydb.py initialise\n\n# Add users to the database\ndocker run --rm -v udpproxy-data:/app/data -it ap-udpproxy keydb.py add 10001 10002 'Support1' MySecurePassPhrase\n\n# Run the UDP proxy as deamon\ndocker run -d --name ap-udpproxy -v udpproxy-data:/app/data -p 10001-10100:10001-10100 ap-udpproxy\n```\n\nAdapt exposed port according to your usage.\n\n### Managing the Database with Docker\n\nThe Docker container includes an intelligent entrypoint that automatically handles keydb.py commands:\n\n```bash\n# All keydb.py operations work directly:\ndocker run --rm -v udpproxy-data:/app/data -it ap-udpproxy keydb.py list\ndocker run --rm -v udpproxy-data:/app/data -it ap-udpproxy keydb.py add PORT1 PORT2 Name PassPhrase\ndocker run --rm -v udpproxy-data:/app/data -it ap-udpproxy keydb.py remove PORT2\ndocker run --rm -v udpproxy-data:/app/data -it ap-udpproxy keydb.py setname PORT2 NewName\ndocker run --rm -v udpproxy-data:/app/data -it ap-udpproxy keydb.py setpass PORT2 NewPassPhrase\n```\n\n### Viewing Logs and Monitoring\n\nWhen running UDPProxy in Docker, you can monitor logs and status using these commands:\n\n```bash\n# View real-time logs from the running container\ndocker logs -f ap-udpproxy\n\n# View last 100 lines of logs\ndocker logs --tail 100 ap-udpproxy\n\n# View logs with timestamps\ndocker logs -t ap-udpproxy\n\n# Check container status\ndocker ps | grep ap-udpproxy\n\n# Check container resource usage\ndocker stats ap-udpproxy\n\n# Access container shell for debugging\ndocker exec -it ap-udpproxy bash\n\n# View logs inside the container (if available)\ndocker exec ap-udpproxy tail -f /app/data/proxy.log\n```\n\n## Database Management\n\n### keydb.py Commands\n\nThe `keydb.py` script provides comprehensive database management:\n\n```bash\n# Initialize database (first time only)\n./keydb.py initialise\n\n# List all users and their status\n./keydb.py list\n\n# Add new user\n./keydb.py add PORT1 PORT2 Name PassPhrase\n\n# Remove user\n./keydb.py remove PORT2\n\n# Modify existing users\n./keydb.py setname PORT2 NewName           # Change name\n./keydb.py setpass PORT2 NewPassPhrase     # Change passphrase\n./keydb.py setport1 PORT2 NewPORT1         # Change user port\n\n# Examples:\n./keydb.py add 10006 10007 'Engineering' SecurePass123\n./keydb.py setname 10007 'QA Team'\n./keydb.py remove 10007\n```\n\n### Database Notes\n\n- **Automatic Port Listening**: When users are added, udpproxy automatically starts listening on new ports without restart\n- **Port Conflicts**: The system prevents duplicate port assignments\n- **Persistent Storage**: Database is stored in `keys.tdb` file\n- **Backup**: Regularly backup the `keys.tdb` file for disaster recovery\n\n### Security Considerations\n\n- **Passphrase Strength**: Use strong, unique passphrases for each user\n- **Port Range**: Consider using non-standard port ranges to avoid conflicts\n- **Firewall**: Configure firewall rules to allow only necessary ports\n- **Access Control**: Limit access to the server and keydb.py script\n\n## Troubleshooting\n\n### Common Issues\n\n**Build Errors:**\n```bash\n# Missing dependencies\nsudo apt install libtdb-dev python3-tdb build-essential git libssl-dev\n\n# Submodule issues\ngit submodule update --init --recursive --force\n\n# Clean rebuild\nmake distclean \u0026\u0026 make\n```\n\n**Runtime Issues:**\n```bash\n# Check if ports are in use\nnetstat -ln | grep \":10001\"\n\n# Check database\n./keydb.py list\n\n# Restart proxy\npkill udpproxy \u0026\u0026 ./udpproxy\n\n# Check logs\ntail -f proxy.log\n```\n\n**Permission Issues:**\n```bash\n# Make scripts executable\nchmod +x keydb.py start_proxy.sh\n\n# Check database permissions\nls -la keys.tdb\n```\n\n### Debug Mode\n\n```bash\n# Check system logs\njournalctl -f | grep udpproxy\n```\n\n## Testing\n\n### Automated CI Testing\n\nUDPProxy includes comprehensive CI testing to validate UDP and TCP connection functionality:\n\n```bash\n# Run all tests locally\n./run_tests.sh\n\n# Run specific test suites\nsource venv/bin/activate\npytest tests/test_connections.py -v\npytest tests/test_authentication.py -v\n```\n\n## Contributing\n\n1. **Code Style**: Follow existing C++ and Python conventions\n2. **Testing**: Run the test suite before submitting changes\n3. **Documentation**: Update README for new features\n4. **Compatibility**: Ensure changes work with existing databases\n\n## License\n\nUDPProxy is licensed under the GNU General Public License version 3 or later.\n\nSee `COPYING.txt` for full license terms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fardupilot%2Fudpproxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fardupilot%2Fudpproxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fardupilot%2Fudpproxy/lists"}