{"id":17321626,"url":"https://github.com/jamesits/linux-gre-keepalive","last_synced_at":"2025-04-14T15:41:21.509Z","repository":{"id":37636019,"uuid":"244952413","full_name":"Jamesits/linux-gre-keepalive","owner":"Jamesits","description":"High-performance passive (a.k.a. reply-only) GRE keepalive support for Linux, written in eBPF/XDP.","archived":false,"fork":false,"pushed_at":"2021-11-24T19:04:09.000Z","size":102,"stargazers_count":57,"open_issues_count":3,"forks_count":8,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-28T04:35:01.605Z","etag":null,"topics":["ebpf","gre","gre-tunnel","keep-alive","linux","xdp"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Jamesits.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}},"created_at":"2020-03-04T16:42:42.000Z","updated_at":"2025-03-02T20:09:40.000Z","dependencies_parsed_at":"2022-07-12T16:34:56.314Z","dependency_job_id":null,"html_url":"https://github.com/Jamesits/linux-gre-keepalive","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jamesits%2Flinux-gre-keepalive","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jamesits%2Flinux-gre-keepalive/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jamesits%2Flinux-gre-keepalive/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jamesits%2Flinux-gre-keepalive/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Jamesits","download_url":"https://codeload.github.com/Jamesits/linux-gre-keepalive/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248907926,"owners_count":21181433,"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","gre","gre-tunnel","keep-alive","linux","xdp"],"created_at":"2024-10-15T13:38:32.194Z","updated_at":"2025-04-14T15:41:21.480Z","avatar_url":"https://github.com/Jamesits.png","language":"C","readme":"# linux-gre-keepalive\n\nThis eBPF program adds high-performance reply-only GRE keepalive support for Linux kernel.\n\n[![Build Status](https://dev.azure.com/nekomimiswitch/General/_apis/build/status/linux-gre-keepalive?branchName=master)](https://dev.azure.com/nekomimiswitch/General/_build/latest?definitionId=78\u0026branchName=master)\n\nNote: If you don't want to install anything and don't care about some potential security problems, just enable the following 2 options to get native GRE keepalive support on Linux:\n```\nsysctl net.ipv4.conf.default.accept_local=1\nsysctl net.ipv4.conf.all.accept_local=1\n```\n\n## Compatiblity\n\n| Protocol \t| Linux name \t| XDP Executable   \t| Tested Vendors  \t| Comments    \t|\n|----------\t|------------\t|------------------\t|-----------------\t|-------------\t|\n| GRE      \t| gre        \t| keepalive_gre.o  \t| Cisco, MikroTik \t|             \t|\n| GRE6     \t| ip6gre     \t| keepalive_gre6.o \t| MikroTik       \t|             \t|\n\n## Usage\n\nSimply load the correct XDP executable on the tunnel interface you just created. For example, assume you have set up the GRE tunnel as `gre0`, to enable GRE keepalive:\n\n```shell\nip link set dev gre0 xdp object build/keepalive_gre.o\n```\n\nTo disable it without removing the tunnel interface:\n\n```shell\nip link set dev gre0 xdp off\n```\n\nLoading an executable on other types of interfaces is considered an undefined behavior.\n\n## Caveats\n\n### GRE on Cisco IOS XE\n\nOn Cisco IOS XE, you must explicitly configure an ip address or an ipv6 address to make the GRE tunnel actually send something. If you don't configure IP addresses, `debug tunnel keepalive` will still show keepalive packets being sent, but the other end won't receive anything. A valid configuration example:\n\n```\ninterface Tunnel10\n ip address 10.0.0.1 255.255.255.0\n keepalive 1 2\n tunnel source GigabitEthernet1\n tunnel destination your.other.end.ip.address\n tunnel mode gre ip\n```\n\n### GRE6 (ip6gre) keepalive support\n\nGRE6 keepalive is not supported by:\n\n* [Cisco IOS XE](https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/interface/configuration/xe-16-6/ir-xe-16-6-book/ir-gre-ipv6-tunls-xe.html#GUID-B8369497-671A-4B51-A749-A81971011A29)\n* [Juniper Junos OS](https://www.juniper.net/documentation/en_US/junos/topics/concept/gre-keepalive-time-overview.html)\n\nMikroTik RouterOS implements their own GRE IPv6 keepalive with inner GRE header's proto field set to `0x86dd`. This have been implemented by us.\n\n## Building\n\nAssume we are on a Debian 10.\n\n```shell\nsudo apt install build-essential clang llvm libelf-dev gcc-multilib linux-headers-$(dpkg --print-architecture)\nmake all\n```\n\n### Debugging\n\nView compiled bytecode:\n\n```shell\nllvm-objdump -S build/keepalive_gre.o\n```\n\nEnabling debugging output:\n\n```c\n#define DEBUG\n#define DEBUG_PRINT_HEADER_SIZE 32\n```\n\nThen view debug output after enabling it by:\n\n```shell\ncat /sys/kernel/debug/tracing/trace_pipe\n```\n\n## References\n\nHere's a list of awesome articles and projects I found useful:\n\n* [BPF and XDP Reference Guide](https://docs.cilium.io/en/latest/bpf/)\n* [xdp-project/xdp-tutorial](https://github.com/xdp-project/xdp-tutorial)\n* [dpino/xdp_ipv6_filter](https://github.com/dpino/xdp_ipv6_filter)\n* [How GRE Keepalives Work](https://www.cisco.com/c/en/us/support/docs/ip/generic-routing-encapsulation-gre/63760-gre-keepalives-63760.html)\n* [OISF/suricata](https://github.com/OISF/suricata)\n* [iovisor/bpf-docs](https://github.com/iovisor/bpf-docs)\n* [PaulTimmins/linux-gre-keepalive](https://github.com/PaulTimmins/linux-gre-keepalive)\n* [An introduction to Linux virtual interfaces: Tunnels](https://developers.redhat.com/blog/2019/05/17/an-introduction-to-linux-virtual-interfaces-tunnels/)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesits%2Flinux-gre-keepalive","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjamesits%2Flinux-gre-keepalive","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesits%2Flinux-gre-keepalive/lists"}