{"id":24650444,"url":"https://github.com/knneth/libnginx-mod-http-fd-pass","last_synced_at":"2026-05-16T21:34:46.223Z","repository":{"id":274082691,"uuid":"921829690","full_name":"knneth/libnginx-mod-http-fd-pass","owner":"knneth","description":"Nginx module for passing client HTTP(S) connections to another process","archived":false,"fork":false,"pushed_at":"2026-04-03T17:04:49.000Z","size":62,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-03T20:09:37.828Z","etag":null,"topics":["nginx"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/knneth.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-24T17:38:59.000Z","updated_at":"2026-04-03T17:04:54.000Z","dependencies_parsed_at":null,"dependency_job_id":"734be44c-e2ab-4720-a75a-cbf83c1ec9ce","html_url":"https://github.com/knneth/libnginx-mod-http-fd-pass","commit_stats":null,"previous_names":["knneth/libnginx-mod-http-fd-pass"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/knneth/libnginx-mod-http-fd-pass","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knneth%2Flibnginx-mod-http-fd-pass","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knneth%2Flibnginx-mod-http-fd-pass/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knneth%2Flibnginx-mod-http-fd-pass/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knneth%2Flibnginx-mod-http-fd-pass/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/knneth","download_url":"https://codeload.github.com/knneth/libnginx-mod-http-fd-pass/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knneth%2Flibnginx-mod-http-fd-pass/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33119531,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-16T18:38:32.183Z","status":"ssl_error","status_checked_at":"2026-05-16T18:38:29.903Z","response_time":115,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["nginx"],"created_at":"2025-01-25T18:15:05.786Z","updated_at":"2026-05-16T21:34:46.217Z","avatar_url":"https://github.com/knneth.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nginx http_fd_pass module\n\nlibnginx-mod-http-fd-pass is a custom [NGINX](https://github.com/nginx/nginx/) module that passes on incoming client connections to another process using an extended [SimpleCGI (SCGI) protocol](https://en.wikipedia.org/wiki/Simple_Common_Gateway_Interface).\nUniquely, it sends the actual client file descriptor (FD) via an [`SCM_RIGHTS`](https://man7.org/linux/man-pages/man7/unix.7.html#:~:text=SCM_RIGHTS) ancillary message along with the initial HTTP request headers.\n\n## How It Works\n\n1. Receive Request: Nginx accepts a new client connection (HTTP or HTTPS with [Kernel TLS offload](https://docs.kernel.org/networking/tls-offload.html)).\n2. Collect Headers: Once all initial request headers have arrived from the client, the module gathers these headers.\n3. SCGI Forward:\n   - The module forwards the request headers to a backend process over a UNIX domain socket, adhering to the SCGI protocol.\n   - Simultaneously, the client’s file descriptor is passed via an `SCM_RIGHTS` ancillary message.\n4. Connection Handoff:\n   - For HTTP connections, or for HTTPS connections using kTLS offload (both receive and send), nginx is finished with the connection after handing it off.\n     The backend process owns the client connection FD going forward.\n\nThis setup effectively lets you implement advanced workflows in your SCGI-based backend (such as specialized I/O handling, zero-copy operations, or custom protocols) while using NGINX as the initial request router.\n\n## Features\n\n- SCGI Integration: Uses the SCGI protocol to transmit request headers to another process.\n- FD Handoff via `SCM_RIGHTS`: Passes the client’s file descriptor to the backend, enabling direct control of the connection.\n- Minimal Overhead: Once NGINX hands off the connection, it no longer processes subsequent data for the request (if HTTP or kTLS offload is used in both directions).\n- Simple Directives: `fd_pass` can be configured on specific locations, making it easy to enable or disable per context.\n\n## Limitations / Notes\n\n- SCGI-only: This module uses SCGI; it does not support FastCGI, environment variables, or other CGI interfaces.\n- Advanced Use Cases: Handing off the FD is powerful but also complex; ensure your SCGI backend can handle raw socket I/O.\n- TLS Support: For TLS connections, the module works best with kTLS enabled for both receiving and sending.\n  Otherwise, nginx must continue handling SSL/TLS on the connection.\n\n\u003e [!NOTE]\n\u003e Specifically for OpenSSL version 3.0 and 3.1, only sending is possible to offload for TLSv1.3 clients.\nFor these clients, Nginx retains ownership of receiving and decrypting data from the client in user space, and forwards the decrypted data to the backend over UNIX socket.\nStill, the backend process will have ownership over sending data to the client since encryption uses Kernel TLS offload.\n\u003e | OpenSSL version | kTLS offloads for TLSv1.2 | kTLS offloads for TLSv1.3 |\n\u003e | --- | --- | --- |\n\u003e | 3.0, 3.1 | Encrypt and decrypt (full handover) | Encrypt only (partial socket handover from nginx) |\n\u003e | 3.2 and later | Encrypt and decrypt (full handover) | Encrypt and decrypt (full handover) |\n\n## Installation\n\nInstall a dpkg package from the Releases page or build it from source as outlined below.\n\nBuilding a module on Debian/Ubuntu:\n\n1. Clone the repository:\n   ```\n   git clone https://github.com/knneth/libnginx-mod-http-fd-pass.git\n   cd libnginx-mod-http-fd-pass\n   ```\n2. Build the package:\n   ```\n   dpkg-buildpackage --build=binary --unsigned-changes --unsigned-buildinfo\n   ```\n3. Install the package (change the version number as necessary):\n   ```\n   sudo apt install ../libnginx-mod-http-fd-pass_1.0.0-0_amd64.deb\n   ```\n\nAlternatively, it can be compiled into the nginx server (embedded applications):\n\n1. Clone the repository:\n   ```\n   git clone https://github.com/knneth/libnginx-mod-http-fd-pass\n   ```\n2. Obtain and extract nginx source code (matching your desired NGINX version)\n   ```\n   curl -OLR https://nginx.org/download/nginx-x.x.x.tar.gz\n   tar xvzf nginx-x.x.x.tar.gz\n   cd nginx-x.x.x\n   ```\n3. Configure nginx with this module:\n   ```\n   ./configure --add-module=../libnginx-mod-http-fd-pass --with-http_ssl_module [other-options]\n   make -j\n   ```\n\n## Configuration\n\nTo enable the module, add the `fd_pass` directive in the appropriate `location` block in your site configuration. For example:\n\n```nginxconf\nlocation = /fd_pass_test {\n    fd_pass unix:/run/fd_pass_test.sock;\n}\n```\n\n## Example SCGI Backend Logic\n\nYour SCGI backend must:\n- Receive the netstring-encoded SCGI headers from the UNIX domain socket.\n- Extract the client FD from the received ancillary data (`SCM_RIGHTS`).\n- Interact directly with the client socket. For HTTP, TLSv1.2, or when the SCGI header `KTLS_RX=0` is absent, you can continue reading or writing data to this FD as needed.\n  - Only encryption is offloaded to kTLS when the SCGI header `KTLS_RX=0` is present.\n    You can continue receiving data over the UNIX socket connection, but writing data must use the client FD.\n    Upgrade to OpenSSL 3.2 or later to support full connection handover for TLSv1.3 clients.\n\n# Contributing\n\nWe welcome contributions that enhance functionality, improve performance, or fix bugs.\n\n# License\n\nThis project is licensed under the [BSD 2-Clause \"Simplified\" License](LICENSE).\n\n# Maintainer\n\n- [knneth](https://github.com/knneth)\n\n# Future work\n\nThe upstream NGINX project could introduce FD passing in their `ngx_http_scgi_module` module.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknneth%2Flibnginx-mod-http-fd-pass","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fknneth%2Flibnginx-mod-http-fd-pass","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknneth%2Flibnginx-mod-http-fd-pass/lists"}