{"id":13772568,"url":"https://github.com/msantos/libkeepalive","last_synced_at":"2025-04-28T17:42:09.934Z","repository":{"id":136621432,"uuid":"214200375","full_name":"msantos/libkeepalive","owner":"msantos","description":"LD_PRELOAD library for enabling TCP keepalive socket options","archived":false,"fork":false,"pushed_at":"2023-10-17T12:21:52.000Z","size":38,"stargazers_count":38,"open_issues_count":0,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-30T11:41:35.775Z","etag":null,"topics":["fd","ldpreload","socket","tcp-keepalive"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/msantos.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}},"created_at":"2019-10-10T14:12:33.000Z","updated_at":"2025-02-26T22:50:22.000Z","dependencies_parsed_at":"2024-01-15T03:57:55.913Z","dependency_job_id":"a2071ead-e2c6-43f1-bfff-f2a1110ec4f9","html_url":"https://github.com/msantos/libkeepalive","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/msantos%2Flibkeepalive","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msantos%2Flibkeepalive/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msantos%2Flibkeepalive/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msantos%2Flibkeepalive/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/msantos","download_url":"https://codeload.github.com/msantos/libkeepalive/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251357658,"owners_count":21576749,"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":["fd","ldpreload","socket","tcp-keepalive"],"created_at":"2024-08-03T17:01:05.489Z","updated_at":"2025-04-28T17:42:09.917Z","avatar_url":"https://github.com/msantos.png","language":"C","funding_links":[],"categories":["Libraries"],"sub_categories":[],"readme":"# SYNOPSIS\n\n# client only\n\nLD_PRELOAD=libkeepalive.so *COMMAND* *ARG* *...*\n\n# server only\n\nLD_PRELOAD=libkeepalive_listen.so *COMMAND* *ARG* *...*\n\n# client and server\n\nLD_PRELOAD=libkeepalive.so:libkeepalive_listen.so *COMMAND* *ARG* *...*\n\n# client and/or server\n\nLD_PRELOAD=libkeepalive_socket.so *COMMAND* *ARG* *...*\n\n# DESCRIPTION\n\nlibkeepalive: set TCP keepalives options\n\nlibkeepalive is a small library for setting various socket options\nrequired for enabling TCP keepalives. Inspired by:\n\n* https://blog.cloudflare.com/when-tcp-sockets-refuse-to-die/\n\n* http://codearcana.com/posts/2015/08/28/tcp-keepalive-is-a-lie.html\n\n* https://tech.instacart.com/the-vanishing-thread-and-postgresql-tcp-connection-parameters-93afc0e1208c\n\n`libkeepalive` works by intercepting calls to `connect(2)` using\n`LD_PRELOAD`. Before `connect(2)`ing, `setsockopt(2)` is called using\nthe configured socket options.\n\n`libkeepalive_listen` works by intercepting calls to `listen(2)`\nusing `LD_PRELOAD`. Socket options are set when the application calls\n`listen(2)`. Socket options for `accept`(2)'ed fd's are inherited from\nthe listener socket.\n\n`libkeepalive_socket` intercepts calls to `socket(2)` using\n`LD_PRELOAD`. Socket options are set after the application calls\n`socket(2)`.\n\nlibkeepalive requires the program to be dynamically linked and will\nnot work with statically linked programs or programs that directly\nmake syscalls.\n\nlibkeepalive is a small LD_PRELOAD library to enable TCP keepalives and\nTCP_USER_TIMEOUT on any sockets opened by dynamically linked applications,\neither outbound (connect(2), using libkeepalive.so), inbound (listen(2),\nusing libkeepalive_listen.so) or any INET/INET6 socket (socket(2),\nusing libkeepalive_socket.so).\n\nThe typical situation is that a long lasting connection is established\nacross some network boundary. The connection is idle and some intermediary\ndevice drops the connection state. Enabling TCP keepalives will keep the\nconnection active and, if the connection is dropped by the intermediary,\nforce it to be closed.\n\nAlternatively, the connection can be dropped by the intermediary while\nthere is still pending data. The TCP_USER_TIMEOUT setting will force\nthe connection to be closed.\n\n# ENVIRONMENT VARIABLES\n\nSetting options to 0 will use the system default.\n\n## COMMON VARIABLES\n\n`LIBKEEPALIVE_DEBUG`\n: Write errors to stdout (default: disabled). Set to any value to enable.\n\n```\nLIBKEEPALIVE_DEBUG=1\n```\n\n`TCP_KEEPIDLE`\n: The number of seconds a connection is idle before TCP keepalives are sent\n(default: 15).\n\n`TCP_KEEPCNT`\n: If the peer does not respond, the number of keepalives sent before\nterminating the connection. Note: see `tcp`(7) for interaction of\n`TCP_KEEPCNT` with `TCP_USER_TIMEOUT` (default: 9).\n\n`TCP_KEEPINTVL`\n: Configures the interval in seconds a keepalive is retried if the peer\nis not responding (default: 15).\n\n`TCP_MAXSEG`\n: Sets the maximum segment size (MSS) for outgoing packets.\n\n`TCP_WINDOW_CLAMP`\n: Limits the advertised window.\n\n`TCP_USER_TIMEOUT`\n: Number in milliseconds before an inactive connection in ESTABLISHED\nstate is terminated.\n\nWhen `TCP_USER_TIMEOUT` is enabled (default), the TCP keepalive count is\nignored. The connection will be terminated when the `TCP_USER_TIMEOUT`\nis reached.\n\nThe default `TCP_USER_TIMEOUT` is calculated using:\n\n```\ntcp_keepidle + tcp_keepintvl * tcp_keepcnt\n```\n\nPossible values:\n\n* `0`: use system default\n* `-1`: derive from other settings (default)\n* `\u003e0`: set to this value\n\n## libkeepalive, libkeepalive_socket\n\n`TCP_SYNCNT`\n: Number of SYN packets sent on `connect(2)` (default: 0 (system default))\n\n## libkeepalive_listen, libkeepalive_socket\n\n`TCP_DEFER_ACCEPT`\n: Avoid waking up the server process until data is sent by the\nclient. Number of seconds to wait (default: 0 (disabled))\n\n# EXAMPLES\n\n## netcat\n\n```shell\n## Use strace to verify setsockopt(2) is called\n\n# run in a shell\nLD_PRELOAD=libkeepalive_listen.so strace -e trace=network nc -k -l 9090\n\n# in another shell\nLD_PRELOAD=libkeepalive.so strace -e trace=network nc 127.0.0.1 9090\n\n# in another shell\nLD_PRELOAD=libkeepalive_socket.so strace -e trace=network nc 127.0.0.1 9090\n```\n\n### `TCP_USER_TIMEOUT`\n\n```shell\n$ time LD_PRELOAD=libkeepalive.so TCP_USER_TIMEOUT=5000 nc -vvv 8.8.8.8 22\nnc: connect to 8.8.8.8 port 22 (tcp) failed: Connection timed out\n\nreal    0m5.038s\nuser    0m0.005s\nsys     0m0.008s\n```\n\nUsing the settings described in https://tech.instacart.com/the-vanishing-thread-and-postgresql-tcp-connection-parameters-93afc0e1208c:\n\n```shell\n# keepalives: 1          # Interpreted as a boolean\n# keepalives_idle: 2     # seconds\n# keepalives_interval: 3 # seconds\n# keepalives_count: 3    # a count\n# tcp_user_timeout: 9000 # In milliseconds\n$ time LD_PRELOAD=libkeepalive.so TCP_KEEPIDLE=2 TCP_KEEPINTVL=3 TCP_KEEPCNT=3 TCP_USER_TIMEOUT=9000 nc -vvv 8.8.8.8 22\nnc: connect to 8.8.8.8 port 22 (tcp) failed: Connection timed out\n\nreal    0m9.034s\nuser    0m0.001s\nsys     0m0.010s\n```\n\n# ALTERNATIVES\n\n* [libkeepalive](http://libkeepalive.sourceforge.net/)\n\n  The original libkeepalive, the one included in your package system,\n  that this library unfortunately (and unintentionally) name squatted.\n\n# SEE ALSO\n\n*socket*(7), *tcp*(7), *connect*(2), *listen*(2), *accept*(2), *setsockopt*(2)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsantos%2Flibkeepalive","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmsantos%2Flibkeepalive","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsantos%2Flibkeepalive/lists"}