{"id":28184129,"url":"https://github.com/robur-coop/tlstunnel","last_synced_at":"2025-05-16T05:13:11.595Z","repository":{"id":49791393,"uuid":"270625989","full_name":"robur-coop/tlstunnel","owner":"robur-coop","description":"A TLS reverse proxy unikernel","archived":false,"fork":false,"pushed_at":"2025-03-10T12:02:35.000Z","size":54,"stargazers_count":36,"open_issues_count":7,"forks_count":2,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-05-12T05:58:24.155Z","etag":null,"topics":["mirageos","reverse-proxy","stunnel","tls"],"latest_commit_sha":null,"homepage":null,"language":"OCaml","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robur-coop.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2020-06-08T10:29:47.000Z","updated_at":"2025-03-10T12:02:35.000Z","dependencies_parsed_at":"2024-01-09T12:27:32.248Z","dependency_job_id":"67765d5f-a16b-496b-bebf-70bb4be5253f","html_url":"https://github.com/robur-coop/tlstunnel","commit_stats":null,"previous_names":["robur-coop/tlstunnel"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robur-coop%2Ftlstunnel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robur-coop%2Ftlstunnel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robur-coop%2Ftlstunnel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robur-coop%2Ftlstunnel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robur-coop","download_url":"https://codeload.github.com/robur-coop/tlstunnel/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254470975,"owners_count":22076587,"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":["mirageos","reverse-proxy","stunnel","tls"],"created_at":"2025-05-16T05:12:14.992Z","updated_at":"2025-05-16T05:13:11.576Z","avatar_url":"https://github.com/robur-coop.png","language":"OCaml","funding_links":[],"categories":[],"sub_categories":[],"readme":"## TLStunnel\n\nThis is a MirageOS unikernel accepting TLS connections via the public (service)\nnetwork interface on frontend-port, and proxying them using TCP via the private\nnetwork interface to backend-ip and backend-port. A client connecting to\nTLStunnel has to establish a TLS connection, which payload is forwarded to the\nbackend service via TCP.\n\nTLStunnel can be used for load-balancing - using multiple TLStunnel on the\nfrontend doing expensive crypto operations (asymmetrics TLS handshakes and\nsymmetric cryptography) with a single (or multiple) backend-services which\ncommunicate via plain TCP.\n\nSecurity-wise only the TLStunnel needs access to the private key of the X.509\ncertificate(s). When TLStunnel is configured to do client authentication, only\nvalid clients can access the backend service, limiting the attack surface\ndrastically.\n\n## Usage\n\nExecuting TLStunnel requires two IP addresses: one is the public facing one, the\nother is on the private network (where TCP connections are forwarded to).\nConfiguration can be done via a command-line utility on the private network. The\nX.509 certificate should be available via DNS (see\n[dns-primary-git](https://github.com/robur-coop/dns-primary-git) and\n[dns-letsencrypt-secondary](https://github.com/robur-coop/dns-letsencrypt-secondary/)).\n\nLet's consider your public IP address being 1.2.3.4/24 (with default gateway\n1.2.3.1). You use 192.168.0.4/24 as your private network. Your DNS server is\n1.2.3.5 with the key tlstunnel._update.example.org.\n\nStarting TLStunnel:\n\n```bash\n$ truncate -s 1m /var/db/tlstunnel\n$ solo5-hvt --net:service=tap0 --net:private=tap10 --block:storage=/var/db/tlstunnel -- \\\n  tlstunnel/unikernel/dist/tlstunnel.hvt --ipv4=1.2.3.4/24 --ipv4-gateway=1.2.3.1 \\\n  --private-ipv4=192.168.0.4/24 --domains=example.org \\\n  --dns-server=1.2.3.5 --dns-key=tlstunnel._update.example.org:SHA256:m2gls0y3ZMN4DVKx37x/VoKEdll4J2A9qNIl6JIz2z4= \\\n  --key-seed=ROkD8o/Xrc4ScDdxM8cV1+4eQiWUEul+3I1twW+I15E= \\\n  --key=9Fe92fogykIAPBJZU4FUsmpRsAy6YDajIkdSRs650zM=\n```\n\nNow, once tlstunnel managed to get a certificate via DNS, you can already\nconnect to https://1.2.3.4 and should see the certificate:\n\n```bash\n$ openssl s_client -connect 1.2.3.4:443\n$ curl https://1.2.3.4\n```\n\nTo configure TLStunnel's forwarding, where a specified hostname will be\nforwarded to an IP address and port pair, you have to use the binary\n`tlstunnel-client` from the `client` subfolder. The communication is\nauthenticated using the shared secret passed to TLStunnel (`--key=secret`).\n\nThe configuration is kept in the block device (in a robust way, i.e. on change\nfirst the new data is written and afterwards the superblock is updates).\n\n```bash\n$ cd tlstunnel/client\n$ dune build\n\n# Listing all configured hostnames:\n$ _build/install/default/bin/tlstunnel-client list --key=9Fe92fogykIAPBJZU4FUsmpRsAy6YDajIkdSRs650zM= -r 192.168.0.4:1234\n\n# Adding a new forward:\n$ _build/install/default/bin/tlstunnel-client add --key=9Fe92fogykIAPBJZU4FUsmpRsAy6YDajIkdSRs650zM= -r 192.168.0.4:1234 test.example.org 192.168.0.42 80\n\n# Removing a foward:\n$ _build/install/default/bin/tlstunnel-client remove --key=9Fe92fogykIAPBJZU4FUsmpRsAy6YDajIkdSRs650zM= -r 192.168.0.4:1234 test.example.org\n```\n\n## Installation from source\n\nTo install this unikernel from source, you need to have\n[opam](https://opam.ocaml.org) (\u003e= 2.0.0) and\n[ocaml](https://ocaml.org) (\u003e= 4.08.0) installed. Also,\n[mirage](https://mirageos.org) is required (\u003e= 4.5.0). Please follow the\n[installation instructions](https://mirageos.org/wiki/install).\n\nThe following steps will clone this git repository and compile the unikernel:\n\n```bash\n$ git clone https://github.com/robur-coop/tlstunnel.git\n$ cd tlstunnel/unikernel \u0026\u0026 mirage configure -t \u003cyour-favourite-target\u003e\n$ make depend\n$ make build\n```\n\n## Installing as binary\n\nBinaries are available at [Reproducible OPAM\nbuilds](https://builds.robur.coop/job/tlstunnel/), see [Deploying binary MirageOS\nunikernels](https://hannes.robur.coop/Posts/Deploy) and [Reproducible MirageOS\nunikernel builds](https://hannes.robur.coop/Posts/ReproducibleOPAM) for details.\n\n## Questions?\n\nPlease open an issue if you have questions, feature requests, or comments.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobur-coop%2Ftlstunnel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobur-coop%2Ftlstunnel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobur-coop%2Ftlstunnel/lists"}