{"id":17526479,"url":"https://github.com/AlexxIT/pnproxy","last_synced_at":"2025-03-06T06:30:32.491Z","repository":{"id":252385836,"uuid":"840273645","full_name":"AlexxIT/pnproxy","owner":"AlexxIT","description":"Plug and Proxy is a simple home proxy for managing Internet traffic","archived":false,"fork":false,"pushed_at":"2024-09-10T17:41:15.000Z","size":68,"stargazers_count":21,"open_issues_count":1,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-30T04:12:10.185Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AlexxIT.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":"2024-08-09T10:41:14.000Z","updated_at":"2024-10-03T19:05:56.000Z","dependencies_parsed_at":"2024-09-10T19:21:04.948Z","dependency_job_id":"84bf554c-e4bb-45f6-8520-798568ae5edb","html_url":"https://github.com/AlexxIT/pnproxy","commit_stats":null,"previous_names":["alexxit/pnproxy"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexxIT%2Fpnproxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexxIT%2Fpnproxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexxIT%2Fpnproxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexxIT%2Fpnproxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlexxIT","download_url":"https://codeload.github.com/AlexxIT/pnproxy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242161190,"owners_count":20081821,"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":[],"created_at":"2024-10-20T15:01:48.986Z","updated_at":"2025-03-06T06:30:32.471Z","avatar_url":"https://github.com/AlexxIT.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# pnproxy\n\n**pnproxy** - Plug and Proxy is a simple home proxy for managing Internet traffic.\n\nFeatures:\n\n- work on all devices in the local network without additional settings\n- proxy settings for selected sites only\n- ad blocking support (like AdGuard)\n\nTypes:\n\n- DNS proxy\n- Reverse proxy for HTTP and TLS (level 4 proxy)\n- HTTP anonymous proxy\n\n## Install\n\n- Binary - [nightly.link](https://nightly.link/AlexxIT/pnproxy/workflows/build/master)\n- Docker - [alexxit/pnproxy](https://hub.docker.com/r/alexxit/pnproxy)\n- Home Assistant Add-on - [alexxit/hassio-addons](https://github.com/AlexxIT/hassio-addons)\n\n## Setup\n\nFor example, you want to block ads and also forward all Twitter traffic through external proxy server.\nAnd want it to work on all home devices without additional configuration on each device.\n\n1. Install pnproxy on any server in your home network (ex. IP: `192.168.1.123`).\n   It is important that ports 53, 80 and 443 be free on this server.\n2. Create `pnproxy.yaml`\n   ```yaml\n   hosts:\n     adblock: doubleclick.net googlesyndication.com\n     tunnel: twitter.com twimg.com t.co x.com\n   \n   dns:\n     listen: \":53\"\n     rules:\n       - name: adblock                         # name from hosts block\n         action: static address 127.0.0.1      # block this sites\n       - name: tunnel                          # name from hosts block\n         action: static address 192.168.1.123  # redirect this sites to pnproxy\n     default:\n       action: dns server 8.8.8.8              # resolve DNS for all other sites\n   \n   http:\n     listen: \":80\"\n     rules:\n       - name: tunnel                          # name from hosts block\n         action: redirect scheme https         # redirect this sites from HTTP to TLS module\n     default:\n       action: raw_pass\n   \n   tls:\n     listen: \":443\"\n     rules:\n       - name: tunnel                          # name from hosts block\n         action: proxy_pass host 123.123.123.123 port 3128  # forward this sites to external HTTP proxy\n     default:\n       action: raw_pass\n   \n   proxy:\n     listen: \":8080\"                           # optionally run local HTTP proxy\n   \n   log:\n     level: trace                              # optionally increase log level (default - info)\n   ```\n3. Setup DNS server for your home router to `192.168.1.123`.\n\nOptionally, instead of step 3, you can verify that everything works by configuring an HTTP proxy to `192.168.1.123:8080` on your PC or mobile device.\n\n## Configuration\n\nBy default, the app looks for the `pnproxy.yaml` file in the current working directory.\n\n```shell\npnproxy -config /config/pnproxy.yaml\n```\n\nBy default all modules disabled and don't listen any ports.\n\n## Module: Hosts\n\nStore lists of site domains for use in other modules.\n\n- Name comparison includes all subdomains, you don't need to specify them separately!\n- Names can be written with spaces or line breaks. Follow [YAML syntax](https://yaml-multiline.info/).\n\n```yaml\nhosts:\n  list1: site1.com site2.com site3.net\n  list2: |\n    site1.com static.site1.cc\n    site2.com cdnsite2.com\n    site3.in site3.com site3.co.uk\n```\n\n## Module: DNS\n\nRun DNS server and act as DNS proxy.\n\n- Can protect from MITM DNS attack using [DNS over TLS](https://en.wikipedia.org/wiki/DNS_over_TLS) or [DNS over HTTPS](https://en.wikipedia.org/wiki/DNS_over_HTTPS) \n- Can work as AdBlock like [AdGuard](https://adguard.com/)\n\nEnable server:\n\n```yaml\ndns:\n  listen: \":53\"\n```\n\nRules action supports setting `static address` only:\n\n- Useful for ad blocking.\n- Useful for routing some sites traffic through pnproxy.\n\n```yaml\ndns:\n  rules:\n    - name: adblocklist\n      action: static address 127.0.0.1\n    - name: list1 list2 site4.com site5.net\n      action: static address 192.168.1.123\n```\n\nDefault action supports [DNS](https://en.wikipedia.org/wiki/Domain_Name_System), [DOT](https://en.wikipedia.org/wiki/DNS_over_TLS) and [DOH](https://en.wikipedia.org/wiki/DNS_over_HTTPS) upstream:\n\n- Important to use server IP-address, instead of a domain name\n\n```yaml\ndns:\n  default:\n    # action - dns or dot or doh\n    action: dns server 8.8.8.8\n```\n\nSupport build-in providers - `cloudflare`, `google`, `quad9`, `opendns`, `yandex`:\n\n- all this providers support DNS, DOH and DOT technologies.\n\n```yaml\ndns:\n  default:\n    action: dot provider google\n```\n\nTotal config:\n\n```yaml\ndns:\n  listen: \":53\"\n  rules:\n    - name: adblocklist\n      action: static address 127.0.0.1\n    - name: list1 list2 site4.com site5.net\n      action: static address 192.168.1.123\n  default:\n    action: doh provider cloudflare\n```\n\n## Module: HTTP\n\nRun HTTP server and act as reverse proxy.\n\nEnable server:\n\n```yaml\nhttp:\n  listen: \":80\"\n```\n\nRules action supports setting `redirect scheme https` with optional code:\n\n- Useful for redirect all sites traffic to TLS module.\n\n```yaml\nhttp:\n  rules:\n    - name: list1 list2 site4.com site5.net\n      # code - any number (default - 307)\n      action: redirect scheme https\n```\n\nRules action supports setting `raw_pass`:\n\n```yaml\nhttp:\n  rules:\n    - name: list1 list2 site4.com site5.net\n      action: raw_pass\n```\n\nRules action supports setting `proxy_pass`:\n\n- Useful for passing all sites traffic to additional local or remote proxy.\n\n```yaml\nhttp:\n  rules:\n    - name: list1 list2 site4.com site5.net\n      # host and port - mandatory\n      # username and password - optional\n      # type - socks5 (default - http)\n      action: proxy_pass host 123.123.123.123 port 3128 username user1 password pasw1\n```\n\nDefault action support all rules actions:\n\n```yaml\nhttp:\n  default:\n    action: raw_pass\n```\n\n## Module: TLS\n\nRun TCP server and act as Layer 4 reverse proxy.\n\nEnable server:\n\n```yaml\ntls:\n  listen: \":443\"\n```\n\nRules action supports setting `raw_pass`:\n\n- Useful for forward HTTPS traffic to another reverse proxies with custom port.\n\n```yaml\ntls:\n  rules:\n    - name: list1 list2 site4.com site5.net\n      # host - optional rewrite connection IP-address\n      # port - optional rewrite connection port\n      action: raw_pass host 123.123.123.123 port 10443\n```\n\nRules action supports setting `proxy_pass`:\n\n- Useful for passing all sites traffic to additional local or remote proxy.\n\n```yaml\ntls:\n  rules:\n    - name: list1 list2 site4.com site5.net\n      # host and port - mandatory\n      # username and password - optional\n      # type - socks5 (default - http)\n      action: proxy_pass host 123.123.123.123 port 3128 username user1 password pasw1\n```\n\nRules action supports setting `split_pass`:\n\n- Can try to protect from hardware MITM HTTPS attack.\n\n```yaml\ntls:\n  rules:\n    - name: list1 list2 site4.com site5.net\n      action: split_pass\n```\n\nDefault action support all rules actions:\n\n```yaml\ntls:\n  default:\n    action: raw_pass\n```\n\n## Module: Proxy\n\nRun HTTP proxy server. This module does not have its own rules. It uses the HTTP and TLS module rules.\nYou can choose not to run DNS, HTTP, and TLS servers and use pnproxy only as HTTP proxy server.\n\nEnable server:\n\n```yaml\nproxy:\n  listen: \":8080\"\n```\n\n## Tips and Tricks\n\n**Mikrotik DNS fail over script**\n\n- Add as System \u003e Scheduler \u003e Interval `00:01:00`\n\n```\n:global server \"192.168.1.123\"\n\n:do {\n  :resolve google.com server $server\n} on-error={\n  :global server \"8.8.8.8\"\n}\n\n:if ([/ip dns get servers] != $server) do={\n  /ip dns set servers=$server\n}\n```\n\n## Known bugs\n\nIn rare cases, due to [HTTP/2 connection coalescing](https://blog.cloudflare.com/connection-coalescing-experiments) technology, some site may not work properly when using a TCP/TLS Layer 4 proxy. In HTTP proxy mode everything works fine. Everything works fine in Safari browser (it doesn't support this technology). In Firefox, this feature can be disabled - `network.http.http2.coalesce-hostnames`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAlexxIT%2Fpnproxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAlexxIT%2Fpnproxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAlexxIT%2Fpnproxy/lists"}