{"id":13508217,"url":"https://github.com/cloudflare/tubular","last_synced_at":"2025-04-06T12:13:01.856Z","repository":{"id":40382997,"uuid":"459624512","full_name":"cloudflare/tubular","owner":"cloudflare","description":"BSD socket API on steroids","archived":false,"fork":false,"pushed_at":"2024-09-27T17:16:24.000Z","size":3752,"stargazers_count":270,"open_issues_count":7,"forks_count":13,"subscribers_count":13,"default_branch":"main","last_synced_at":"2024-10-08T12:48:01.529Z","etag":null,"topics":["ebpf","go","sockets"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudflare.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2022-02-15T14:55:42.000Z","updated_at":"2024-09-20T01:56:09.000Z","dependencies_parsed_at":"2024-06-20T11:58:18.040Z","dependency_job_id":"a182ea3e-350b-44f3-9b6d-a54e0783c694","html_url":"https://github.com/cloudflare/tubular","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Ftubular","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Ftubular/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Ftubular/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Ftubular/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudflare","download_url":"https://codeload.github.com/cloudflare/tubular/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247478331,"owners_count":20945266,"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","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":["ebpf","go","sockets"],"created_at":"2024-08-01T02:00:49.898Z","updated_at":"2025-04-06T12:13:01.838Z","avatar_url":"https://github.com/cloudflare.png","language":"C","funding_links":[],"categories":["C","Networking \u0026 Performance","go"],"sub_categories":["Traffic Analysis \u0026 Filtering"],"readme":"tubular\n===\n\nThe control plane for BPF socket lookup. Steers traffic that arrives via the\n[tubes of the Internet][1] to processes running on the machine. Its much more\nflexible than traditional BSD `bind` semantics:\n\n* You can bind to all ports on an IP\n* You can bind to a subnet instead of an IP\n* You can bind to all ports on a subnet\n\n__Note:__ Requires at least Linux v5.10.\n\nQuickstart\n---\n\n```sh\n# Install and load tubular\n$ go install github.com/cloudflare/tubular/cmd/tubectl@latest\n$ sudo tubectl load\n\n# Send port 4321 traffic on all loopback IPs to the foo label.\n$ sudo tubectl bind foo tcp 127.0.0.0/8 4321\n\n# Set up a server and register the listening socket under the foo label\n$ nc -k -l 127.0.0.1 9999 \u0026\n$ sudo tubectl register-pid $! foo tcp 127.0.0.1 9999\n\n# Send a message!\n$ echo $USER | nc -q 1 127.0.0.23 4321\n```\n\nThe real power is in the `bind` command.\n\n```sh\n# Send HTTP traffic on a /24 to the foo label.\n$ sudo tubectl bind foo tcp 127.0.0.0/24 80\n$ echo $USER | nc -q 1 127.0.0.123 80\n\n# Send TCP traffic on all ports of a specific IP to the foo label.\n$ sudo tubectl bind foo tcp 127.0.0.22 0\n$ echo $USER | nc -q 1 127.0.0.22 $((1 + $RANDOM))\n```\n\nIntegrating with tubular\n---\n\nTCP servers are compatible with tubular out of the box. For UDP you need to\nset some additional socket options and change the way you send replies.\n\nIn general, you will have to **register your sockets with tubular**. The easiest\nway is to use `tubectl register-pid` combined with a systemd service of\n[Type=notify][3]. It's also possible to use systemd socket activation combined\nwith `tubectl register`, but this setup is more complicated than `register-pid`.\n\n**[The example](example/README.md) shows how to use `register-pid` with a TCP\nand UDP echo server.**\n\nTesting\n---\n\n`tubular` requires at least Linux v5.10 with unprivileged bpf enabled.\n\n```sh\n$ sysctl kernel.unprivileged_bpf_disabled\nkernel.unprivileged_bpf_disabled = 0 # must be zero\n$ make test\n```\n\n[1]: https://en.wikipedia.org/wiki/Series_of_tubes\n[2]: https://github.com/amluto/virtme/\n[3]: https://www.freedesktop.org/software/systemd/man/systemd.service.html#Type=\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Ftubular","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudflare%2Ftubular","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Ftubular/lists"}