Skip to content

Add Nginx Reverse Proxy guide for Pi-hole v6#1379

Open
DoctorD90 wants to merge 7 commits into
pi-hole:masterfrom
DoctorD90:master
Open

Add Nginx Reverse Proxy guide for Pi-hole v6#1379
DoctorD90 wants to merge 7 commits into
pi-hole:masterfrom
DoctorD90:master

Conversation

@DoctorD90
Copy link
Copy Markdown

What does this PR aim to accomplish?:

Documentation of the Nginx Proxy configuration process for the new Pi-hole v6 architecture. Plus additional small updates to README.md (I've left the respective commits in place to facilitate a quick review).

How does this PR accomplish the above?:

The guide covers HTTP/HTTPs ports management, WebSocket proxying, SSL/TLS management, and optional advanced authentication layers like Basic Auth and mTLS. Each step has been verified through multiple test runs to ensure a reliable implementation. Special attention was given to security hardening, favoring modern cryptographic standards and high-strength configurations over legacy defaults.


By submitting this pull request, I confirm the following:

  1. I have read and understood the contributors guide, as well as this entire template. I understand which branch to base my commits and Pull Requests against.
  2. I have commented my proposed changes within the code and I have tested my changes.
  3. I am willing to help maintain this change if there are issues with it later.
  4. It is compatible with the EUPL 1.2 license
  5. I have squashed any insignificant commits. (git rebase)
  6. I have checked that another pull request for this purpose does not exist.
  7. I have considered, and confirmed that this submission will be valuable to others.
  8. I accept that this submission may not be used, and the pull request closed at the will of the maintainer.
  9. I give this submission freely, and claim no ownership to its content.

  • I have read the above and my PR is ready for review. Check this box to confirm

DoctorD90 added 3 commits May 9, 2026 01:48
- Add Debian to list (tested on 12 and 13 releases)
- Add command to exit the python virtual environment
- Sort commands for running the server, exit and entering back in the venv

Signed-off-by: DoctorD90 <DoctorD90@users.noreply.github.com>
Add the  parameter to the  command to automatically update the documentation whenever a change is detected in the local files

Signed-off-by: DoctorD90 <DoctorD90@users.noreply.github.com>
Documentation of the Nginx Proxy configuration process for the new Pi-hole v6 architecture. The guide covers HTTP/HTTPs ports management, WebSocket proxying, SSL/TLS management, and optional advanced authentication layers like Basic Auth and mTLS. Each step has been verified through multiple test runs to ensure a reliable implementation. Special attention was given to security hardening, favoring modern cryptographic standards and high-strength configurations over legacy defaults.

Signed-off-by: DoctorD90 <DoctorD90@users.noreply.github.com>
@DoctorD90 DoctorD90 requested a review from a team as a code owner May 8, 2026 23:56
@netlify
Copy link
Copy Markdown

netlify Bot commented May 8, 2026

Deploy Preview for pihole-docs ready!

Name Link
🔨 Latest commit 1d4e2e8
🔍 Latest deploy log https://app.netlify.com/projects/pihole-docs/deploys/6a07476d07405d0007d473fb
😎 Deploy Preview https://deploy-preview-1379--pihole-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

@yubiuser
Copy link
Copy Markdown
Member

yubiuser commented May 9, 2026

CI test are failing

@DoctorD90
Copy link
Copy Markdown
Author

mmm strange. Not to meme the usual phrase but "on my machine it works" ahah... I mean, running mkdoc serve it worked 🤔 ... it is strange. I will give it a look.

Copy link
Copy Markdown
Contributor

@darkexplosiveqwx darkexplosiveqwx left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. I don't think the "Additional Pre-Authentication" belongs here. IMO it would be better to link to the nginx documentation for this.
    I think the guide should only cover Pi-hole specific configuration needs for setting up nginix and not optional nginx features that dont have to do anything specific with Pi-hole.
  2. How familiar are you with Pi-hole's web setup yourself?
    And did you use AI to write this? Some sections that smell like AI: "Using Nginx is not just about redirection or SSL; it unlocks professional-grade features that go beyond the native capabilities of Pi-hole:" Additionally, some workings of Pi-hole seem to have been guessed and can easily be verified as false.
  3. One of those being the use of WebSocket. Pi-hole v6 does not make any use of WebSocket. If you were to look in the Network tab of your browser, you will find regular HTTP requests for the live updates. The embedded webserver also has WebSocket disabled at compile time:
$ pihole-FTL -vv
[...]
****************************** CivetWeb *****************************
Version:         1.17 (modified by Pi-hole) with mbed TLS 4.0.0
Features:        Files: Yes, TLS: Yes, CGI: No, IPv6: Yes, 
                 WebSockets: No, Server-side JavaScript: No
                 Lua: Yes, Cache: Yes, Stats: No, Compression: No
                 HTTP2: No, Unix domain sockets: No
  1. You are saying "we will restrict via built-in Access Control List (ACL) its web interface to listen only on the local interface (127.0.0.1)"
    Listening on localhost is different than binding to an interface, with your configuration, Pi-hole would still be listening on the wildcard(0.0.0.0) address. Instead of using ACL, you can bind to localhost only. This would be done with:
sudo pihole-FTL --config webserver.port 127.0.0.1:8053"
  1. You mention that one can disable the HTTPS port in Pi-hole if they like, but this will conflict with your idea to use the X.509 certificated generated by Pi-hole. FTL will only refresh the certificate if its own HTTPS port is enabled. I think you should stop using the certificate generated by Pi-hole in nginx.
  2. The PR description says "Each step has been verified through multiple test runs to ensure a reliable implementation", what tests did you run exactly?

@DoctorD90
Copy link
Copy Markdown
Author

@darkexplosiveqwx thank you very much for the deep/complete review! Im getting crazy with CI Test block about format, but I try to reply as better as I can.

  1. I don't think the "Additional Pre-Authentication" belongs here. IMO it would be better to link to the nginx documentation for this.
    I think the guide should only cover Pi-hole specific configuration needs for setting up nginix and not optional nginx features that dont have to do anything specific with Pi-hole.

Honestly I have find even posts on discourse talking about "basic auth", and even author/contributor (apologize, Im not practice with the team) DL6ER seems generated a dedicated feature for the basic auth](https://discourse.pi-hole.net/t/http-basic-authorization-header-support/65956/5). Talking about settings Nginx, I find out it is usefull to cover all - most discussed/requested - topics. Because it is another way to implement a "auth gateway" and far more secure than discussed "basic auth", I think it is related to the Nginx proxy.

2. How familiar are you with Pi-hole's web setup yourself?

I use pihole by many years, but V5; I have lately updated to V6 and I had to debug all issues, looking around internet so I have find out useful to document them cause some of them was tough to find out the root cause.
During this upgrade I have discovered that some feature that wasnt possible/easy to achieve with v5, are now really easy with v6, but they are in the "expert" settings; for example some ciphers settings that could be configured in Civet, but, being belong to me really dedicated to an "hardening" guide more than an Nginx one, I didnt even mention.

   And did you use AI to write this? Some sections that smell like AI: "Using Nginx is not just about redirection or SSL; it unlocks professional-grade features that go beyond the native capabilities of Pi-hole:"

Yes I used the support of AI for the english, cause Im not a native english speaker and I ask AI to review the sentences, but they reflects my thoughts. I took over a week to write everything and document and test in a dedicated environment, so at least the review of english it has been quite useful. As for example, Nginx can handle multiple services and it become easy to manage them via a single tool (Nginx) and it has a lot of possible customizations for each specific need.

Additionally, some workings of Pi-hole seem to have been guessed and can easily be verified as false.

I would be glad if you may fix those, it would be a really nice contribution.

3. One of those being the use of WebSocket. Pi-hole v6 does not make any use of WebSocket. If you were to look in the Network tab of your browser, you will find regular HTTP requests for the live updates. The embedded webserver also has WebSocket disabled at compile time:
$ pihole-FTL -vv
[...]
****************************** CivetWeb *****************************
Version:         1.17 (modified by Pi-hole) with mbed TLS 4.0.0
Features:        Files: Yes, TLS: Yes, CGI: No, IPv6: Yes, 
                 WebSockets: No, Server-side JavaScript: No
                 Lua: Yes, Cache: Yes, Stats: No, Compression: No
                 HTTP2: No, Unix domain sockets: No

Oh well, "strange" and good to know! Strange just because something didnt work at the start and googling and searching around I find out that in many scenarios with modern dashboards, websockets are involved and with those line it worked like a charm. So I assumed it was like that; excuse me, Im not a "wireshark master" or skilled enough to dig into that part of compilation, so I didnt play around with Network tab.
If you think it is better, we may remove the lines about it. Let me know so I can rephrase where I mentioned it, cause currently Im working about the CI Test feedback.

4. You are saying "we will restrict via built-in [Access Control List (ACL)](https://deploy-preview-1379--pihole-docs.netlify.app/ftldns/configfile/?h=acl#acl) its web interface to listen only on the local interface (127.0.0.1)"
   Listening on localhost is different than binding to an interface, with your configuration, Pi-hole would still be listening on the wildcard(`0.0.0.0`) address. Instead of using ACL, you can bind to localhost only. This would be done with:
sudo pihole-FTL --config webserver.port 127.0.0.1:8053"

Uhm... I have find out "webserver.domain" and "webserver.port" so in my comprehension, 1 is for port and another is dedicate to "domain"; the only way I have see was using an ACL that is usually the proper way to achieve restrictions like that. Further more, I used 8053 for HTTP, but 8054s to keep ssl "active", so I ended up with the command "8053,8054s".

5. You mention that one can disable the HTTPS port in Pi-hole if they like, but this will conflict with your idea to use the X.509 certificated generated by Pi-hole. FTL will only refresh the certificate if its own HTTPS port is enabled.

If you have find out some "old" phrase I wrote, please underline it to me; as I said it took me over 1 week, and in the meantime testing and testing, I have review some point, as for example the one about usage of HTTPS of pihole.

I think you should stop using the certificate generated by Pi-hole in nginx.

At the beginning I had in mind to use a dedicated paragraph about SSL certificate, but later on, digging about the Pi-hole certificate, I discovered it is really well handled, renewed, and it can be used without issues, and without touching anything, so for the end average user it is trasparent. I dont catch the point about your concern. May you kindly formulate it more?

6. The PR description says "Each step has been verified through multiple test runs to ensure a reliable implementation", what tests did you run exactly?

I have brought up multiple times machine from scratch, following the normal installation of pi-hole (the simple bash script with prompt after installation, and from that point on, I have copied pasted each command I have wrote in the guide. At a certain point, where some filename was inconsistent, I have stop read again all the text (even cause, being written by me, I didnt even see error, cause brain doesnt catch them after a certain point). I just concentrated about all commands are correct and the PiHole setup work. Feel free to dont trust and think I wrote it in 5 min with AI 😊 I have spent over 1 week to express of writing, delete, and writing back, to express my gratitude to give back the great -free- work I have received thanks to Pihole during latest years. I understand some people concerned, I dont judge.
Im not full practical about all steps to contribute, but Im doing my best to align the quality requested 😊
Im really open to feedback to improve it 😊 so please feel free to underline your opinion, I will review them! Many thanks!

@rdwebdesign
Copy link
Copy Markdown
Member

rdwebdesign commented May 9, 2026

I'll try to help you with the CI tests.

Start with the list of issues: scroll down to the test results, click on the 3 dots button, then click on "-> View details".

image


This will show the last test results. Starting from the Summary: 87 error(s), you can read exactly what is wrong:

image


Examples:

  • docs/guides/reverse_proxy/nginx.md:10 error MD046/code-block-style Code block style [Expected: fenced; Actual: indented]

    Issue in nginx.md - line 10 (the same applies to line 22).

    You started this line with 4 spaces. This is usually used to create "code blocks", but our style guide expects codde blocks using fences (```).
    Apparently you just want this paragraph as part of the !!! info block. The code is not incorrect, but the tests will consider it as a separate code block. TO avoid this issue, use HTML line breaks, like this:

    !!! info "Key Changes in v6"
        Unlike Pi-hole v5, version 6 no longer ...
        <br><br>
        Since Pi-hole v6 handles its own web interface ...
    
  • docs/guides/reverse_proxy/nginx.md:14:1 error MD030/list-marker-space Spaces after list markers [Expected: 1; Actual: 3]

    Issue in nginx.md - lines 14, 15, 16 and 17 (the same applies to lines 22-25).

    You added too many spaces between the list marker and the first character. Use just one:

    * **Enhanced Security:** ...
    
    or 
    
    - **Enhanced Security:** ...
    

Read all other error messages and ask for help if you don't understand something.

@darkexplosiveqwx
Copy link
Copy Markdown
Contributor

My first review was a bit harsh, because I really assumed you didn't do your homework properly. (The WebSocket mistake especially made me question the quality and get harsher)
Nevertheless I'd happily help get things sorted out and improved here.

Yes I used the support of AI for the english, cause Im not a native english speaker and I ask AI to review the sentences, but they reflects my thoughts. I took over a week to write everything and document and test in a dedicated environment, so at least the review of english it has been quite useful.

While both yubiuser and me are not native speakers of English either, we can help remove some of that obvious "marketing language". For a full review of the quality of English promofaux and danshaper are more qualified.

If you think it is better, we may remove the lines about it. Let me know so I can rephrase where I mentioned it, cause currently Im working about the CI Test feedback.

This should definitively be done. I think the relevant sections can be removed entrirely without much rephrasing.
What can be removed entirely for this:

  • The # WebSocket support (For Pi-hole v6 real-time updates) block in the nginx server block
  • The entire The WebSocket Proxy Directives section
  • The entire Real-time dashboard update issues section
  • As for Protocol Control: Fine-tune modern protocols like HTTP/2 or HTTP/3 (QUIC) and manage complex WebSocket handshakes for real-time dashboard updates., I'd hold off on making suggestions on this for now, as I think that the whole Using Nginx is not just about redirection or SSL; it unlocks professional-grade features that go beyond the native capabilities of Pi-hole: section needs a rework

Uhm... I have find out "webserver.domain" and "webserver.port" so in my comprehension, 1 is for port and another is dedicate to "domain"; the only way I have see was using an ACL that is usually the proper way to achieve restrictions like that. Further more, I used 8053 for HTTP, but 8054s to keep ssl "active", so I ended up with the command "8053,8054s".

The ACL is application layer, but the socket binding is at the OS level. I simply prefer socket binding, as it may improve security.

If you have find out some "old" phrase I wrote, please underline it to me; as I said it took me over 1 week, and in the meantime testing and testing, I have review some point, as for example the one about usage of HTTPS of pihole.

Im referring to: In this setup, we let Pi-hole handle its own internal SSL certificates keeping active port 8054. However, if you prefer to use your own custom certificates (e.g., from a different CA or manually managed), you are free to customize the configuration accordingly. In that case, port 8054 does not necessarily need to be activated or exposed.

At the beginning I had in mind to use a dedicated paragraph about SSL certificate, but later on, digging about the Pi-hole certificate, I discovered it is really well handled, renewed, and it can be used without issues, and without touching anything, so for the end average user it is trasparent. I dont catch the point about your concern. May you kindly formulate it more?

While using the X.509 certificate generated by FTL may seem simpler, it introduces some problems down the road.
I have already mentioned the requirement for a HTTPS port to be active in Pi-hole for the renewal to work, but this isnt a blocker.
The concerning thing is that when FTL renews the certificate and changes it on disk, nginx is is not notified of this. nginx needs to be manually reloaded for new X.509 certificates to be used. This would require some awkward scripts and timers, and at that point we might as well generate the certificate manually or use proper tools for this, like certbot with hooks for restarting nginx

Honestly I have find even posts on discourse talking about "basic auth", and even author/contributor (apologize, Im not practice with the team) DL6ER seems generated a dedicated feature for the basic auth](https://discourse.pi-hole.net/t/http-basic-authorization-header-support/65956/5). Talking about settings Nginx, I find out it is usefull to cover all - most discussed/requested - topics. Because it is another way to implement a "auth gateway" and far more secure than discussed "basic auth", I think it is related to the Nginx proxy.

DL6ER is part of the team and the core maintainer of the FTL engine.
While other authentication methods may be used with nginx, there isn't anything specific for Pi-hole here. I do think it could make sense to mention them in the guide, but instead of having a full section here, linking to established guides/docs like nginx's own docs for basic auth or mtls would be better.

@DoctorD90
Copy link
Copy Markdown
Author

@rdwebdesign thank you very much! I ended up installing packages from the CI Test log, the mardown lint-things with npm on a live machine to just run my local own test and fix, but some of them was a bit strange to me. I come from the ages back of "if you can google it, you can google by yourself" so Im used to do not bother people about those thing, trying to find out solution by myself, so thank you very much for the guidance! Really appreciated!

@darkexplosiveqwx no problem! Im used to that nowadays. I completely understand you! AI is a good friend if used with "brain"... but vibecoding is destroying the sector... But dont worry, it isnt my case! So no problem at all! I will review your feedback and try to provide a proper answer to each of your feedback! Thank you!

As per feedback in the relative Pull Request:
- Fixed CI Test error (markdownlint and linkinator);
- Removed the content related to WebSocket;
- Removed the phrase about the reason to adopt Nginx;
- Reworked the SSL topic;
- Review the ACL approach;
- Added Intermediate Mozilla's security standards

Signed-off-by: DoctorD90 <DoctorD90@users.noreply.github.com>
@DoctorD90
Copy link
Copy Markdown
Author

@rdwebdesign I had the time to finish and review the code, but I ended up in a problem with "special link", cause the title was with &; the only solution (to do not adopt HTML) has been to use "and":
error MD051/link-fragments Link fragments should be valid [Context: "[Error Resolution (413 & 414)](#error-resolution-413-414)"]
Im open to tips if there are.

@darkexplosiveqwx here the feedback:

  • Removed the content related to WebSocket;
  • Removed the “marketing” phrase as well after rereading the text with a fresher mind - thanks;
  • Reworked the SSL topic after reading your highlights/suggestion; so focus on the code/test that I completely forgot (even if I was doing that) Nginx has to restart to load the new cert 🤣 you completely destroy my "house of cards" blowing in the perfect my blind spot! Thanks! I was really focus that I completely missed the most simple point.
  • You have more experience with Pi-hole than I do, so if you say it’s common/accepted practice to use webserver.port setting for the web server port, I’ve applied it. For the sake of security, I’ve also left the ACL command in place.
  • I have added links to Nginx official guide about Authentication you provided - thanks!
  • As for the “removing mTLS” part, I personally don’t agree with taking that section out. I put myself in the shoes of an average user: when they have to follow a guide, they should be able to do so even if they’re just starting out. More often than not, authors, even if just to speed up the writing, provide only high-level information or refer readers to other guides. Usually, when I follow a guide, I prefer to have everything I need without having to learn another topic, even if just to test it; this creates a hurdle for me, and in many ways, users often just skip over it. I wrote this with security in mind, because when it comes to “networked devices”, it’s always important to provide a solid guide on the subject. That section provides a very basic but fairly solid mini-guide for testing/implementing mTLS. Personally, I’d like to see basic authentication and mTLS directly integrated into Pi-hole, and I don’t understand why the basic authentication feature was removed, but that’s another topic.

@darkexplosiveqwx
Copy link
Copy Markdown
Contributor

darkexplosiveqwx commented May 14, 2026

You made some good improvements, looking much better now.
I think there are still some points I like to mention:

  • If we already do socket binding to 127.0.0.1 via webserver.port, then the ACL is redundant and doesn't really add any security on-top. I think this would only confuse users if they want to switch off nginx at some point.
  • Additionally, there is no need to restart pihole-FTL.service after changing the config, as FTL listens for config changes and applies them automatically. Feel free to try this on your own system.
  • Regarding mTLS and Basic Auth, I won't be blocked by this any longer. You mention that its a very basic setup for each, that could be fine as an inspiration, especially when linking to the mode in-depth nginx docs.
  • Something that bug me, but isn't caused by you necessarily, is using "SSL certificate". The last version, SSLv3, has been explicitly forbidden to use by RFC 7563. The modern keyword is "TLS". For precision, neither "SSL certificate" nor "TLS certificate" would be correct. The correct term when referring to the certificate standard is "X.509 certificate". SSL/TLS are only what used/uses it. I understand if you want to use the legacy terminology of SSL if it fits the nginx ecosystem. I won't be blocking it.
  • What would you think about enabling HTTP/3 in this guide (or at least commenting it out in the example and making it easy to enable)? HTTP/3 is supported in nginx since 1.25. Debian 13 Trixie ships 1.26 and Fedora 43 ships 1.28. Users can verify if their version includes HTTP/3 support by looking for --with-http_v3_module in nginx -V. Then we should also mention that HTTP/3 uses the QUIC protocol over UDP and requires TLS 1.3 then.

For HTTP/3 I'd be open to add a docs page in another PR myself explaining on how to add a HTTPS recored advertising HTTP/3 to Pi-hole.

Edit:
You mention adding multiple security headers, but all of them besides Strict-Transport-Security are already added by Pi-hole:

$ pihole-FTL --config webserver.headers 
[ X-DNS-Prefetch-Control: off, Content-Security-Policy: default-src 'none'; connect-src 'self'; font-src 'self'; frame-ancestors 'none'; img-src 'self'; manifest-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; form-action 'self', X-Frame-Options: DENY, X-XSS-Protection: 0, X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin ]

AFAIK nginx should preserve them and adding them again would be redundant.

@DoctorD90
Copy link
Copy Markdown
Author

Thanks @darkexplosiveqwx for the so fast review! - I'm already working on another PR to add documentations about contributing on Docs. BTW:

  • Uhm .. As I stated in previous comment, I left the ACL to do not leave "blind spot", but if you underline it again, I trust your knowledge! I will remove the ACL command.

  • I usually restart as "practice" to be sure of a clean setup (closing sockets, refreshing files, and so on). If you advice like that, as before, I will follow your lead.

  • Thanks; as you saw, I have added your links to be sure to provide all possible information to people: a starting secure playground and all information to improve.

  • HONESTLY SPEAKING, I find really only tech guys that "understand" such topic, and most of the time, "X.509" is just for personal-only; on the web and by "majority" (of people who know the topic, ofc), they know about "SSL Certificates", a smaller group the TLS part... The only people I heard mentioning X.509 are experts and ChatGPT 🤣 I'm afraid the majority wouldnt catch its relation; I used "SSL/TLS" to just keep it "as simple as possible". About SSLv3 I agree, and you almost gave me a heart attack, I thought I had mistyped and used SSLv3 in configurations ahahah. Btw, I think that "SSL/TLS" isn't so much related to just Nginx, but wider, to people that "play around" with certificates: to generate them you use mainly openssl, and SSL is the most searched term I think. I would suggest to keep "SSL/TLS" just to avoid to let it become too much technical.

  • HONESTLY SPEAKING - again -, I thought about it ... I was undecided about HTTP3; I havent played with it on my own enough to release something or giving advice to public. HTTP3 is something in my own ToDoList-ToTry; I havent tested about conflicts with directives I provided/suggested, about Pro/Cons, as you said, it involves checks on configurations, versions of different softwares, and so on... I was already "tired" about http2 directive, but I ended up to add it cause it is just 1 line that doesnt conflicts with all others. I thought to add it, but I have so many things to chase that test HTTP3 isnt on top of my list and waiting for it, would have ended in "never release that guide"... but in general, it is the next upgrade in my mind too!

  • Well, I run a customized really restrictive Nginx configuration, and I had such problem with some configuration being hereditary (as client_max_body_size or large_client_header_buffers for example); I decided to add them to avoid "higher-level" directives that could create issues. Now that you made me notice, for example in the default X-XSS-Protection is set to 0 in Pi-hole... I should check in "CivetWeb" (?) how does it handle it... Btw those are just a smaller subset of headers I usually have setted for my self; I have adopted here the most known/used ones. Theoretically speaking, the proxy config could be way smaller... it is me that wanted to avoid hereditary or issues in "custom environments" and give some hints. In my experience, playing with "RProxy" needs attention and updating across used softwares, so sometimes applying general rules /best practice help. That said... If you confirm to me that these may creates issues, I will remove (except HSTS that isnt setup).

@darkexplosiveqwx
Copy link
Copy Markdown
Contributor

It's been quite a while since I last used nginx (on Debian 12 before settling on Caddy), now using Fedora 44.
I wanted to try your config files out just now, but:

Details

My nginx doesnt have `/etc/nginx/sites-available/` nor `/etc/nginx/sites-enabled/`. On Fedora the default is:

$ ls -lA /etc/nginx/
drwxr-xr-x. 1 root root     0 Apr 15 02:00 conf.d
drwxr-xr-x. 1 root root     0 Apr 15 02:00 default.d
-rw-r--r--. 1 root root  1077 Apr 15 02:00 fastcgi.conf
-rw-r--r--. 1 root root  1077 Apr 15 02:00 fastcgi.conf.default
-rw-r--r--. 1 root root  1007 Apr 15 02:00 fastcgi_params
-rw-r--r--. 1 root root  1007 Apr 15 02:00 fastcgi_params.default
-rw-r--r--. 1 root root  2837 Apr 15 02:00 koi-utf
-rw-r--r--. 1 root root  2223 Apr 15 02:00 koi-win
-rw-r--r--. 1 root root 38661 Jan 16 01:00 mime.types
-rw-r--r--. 1 root root  5349 Apr 15 02:00 mime.types.default
-rw-r--r--. 1 root root  1983 Apr 15 02:00 nginx.conf
-rw-r--r--. 1 root root  2630 Apr 15 02:00 nginx.conf.default
-rw-r--r--. 1 root root   636 Apr 15 02:00 scgi_params
-rw-r--r--. 1 root root   636 Apr 15 02:00 scgi_params.default
-rw-r--r--. 1 root root   664 Apr 15 02:00 uwsgi_params
-rw-r--r--. 1 root root   664 Apr 15 02:00 uwsgi_params.default
-rw-r--r--. 1 root root  3611 Apr 15 02:00 win-utf
$ cat /etc/nginx/nginx.conf
# For more information on configuration, see:
#   * Official English Documentation: http://nginx.org/en/docs/
#   * Official Russian Documentation: http://nginx.org/ru/docs/

user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log notice;
pid /run/nginx.pid;

# Load dynamic modules. See /usr/share/doc/nginx/README.dynamic.
include /usr/share/nginx/modules/*.conf;

events {
    worker_connections 1024;
}

http {
    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;

    sendfile            on;
    tcp_nopush          on;
    keepalive_timeout   65;
    types_hash_max_size 4096;

    include             /etc/nginx/mime.types;
    default_type        application/octet-stream;

    server {
        listen       80;
        listen       [::]:80;
        server_name  _;
        root         /usr/share/nginx/html;

        # Load configuration files for the default server block.
        include /etc/nginx/default.d/*.conf;
    }

    # Load modular configuration files from the /etc/nginx/conf.d directory.
    # See http://nginx.org/en/docs/ngx_core_module.html#include
    # for more information.
    include /etc/nginx/conf.d/*.conf;

# Settings for a TLS enabled server.
#
#    server {
#        listen       443 ssl;
#        listen       [::]:443 ssl;
#        http2        on;
#        server_name  _;
#        root         /usr/share/nginx/html;
#
#        ssl_certificate "/etc/pki/nginx/server.crt";
#        ssl_certificate_key "/etc/pki/nginx/private/server.key";
#        ssl_session_cache shared:SSL:1m;
#        ssl_session_timeout  10m;
#        ssl_ciphers PROFILE=SYSTEM;
#        ssl_prefer_server_ciphers on;
#
#        # Load configuration files for the default server block.
#        include /etc/nginx/default.d/*.conf;
#    }

}

  • I think it would be difficult to to tell a user how to make the default fedora install usable, since the main ngnix.conf already has a server block. For my testing I can get around it, but we should keep in mind that the guide is for Debian only.

  • Fedora 44 still doesn't have curl with HTTP/3 support and building from source is such a hassle, so I can't test it that easily. I guess we can hold off HTTP/3 in nginx for now.

  • From playing around for a bit, I think you should also allow the HEAD method, curl -I is useful for testing HTTP without seeing the big responses.

  • The SSL/TLS and X.509 certificate thing is as much of a wider industry issue, especially with libraries names openSSL and nginx using the ssl_* directives. With nginx using "ssl" everywhere, we can't really avoid using the legacy terminology. As said, this is less of a blocker and more of something I wanted to mention in the wider sense.

  • I think most of the security headers should go into the default configuration in Pi-hole, I am for avoiding extra headers in nginx (except HSTS).

@DoctorD90
Copy link
Copy Markdown
Author

It's been quite a while since I last used nginx (on Debian 12 before settling on Caddy), now using Fedora 44.
I wanted to try your config files out just now, but: ...

  • I think it would be difficult to to tell a user how to make the default fedora install usable, since the main ngnix.conf already has a server block. For my testing I can get around it, but we should keep in mind that the guide is for Debian only.

... but now Im running a Fedora VM and testing it 😂 ahahah.... in the end it is just a bunch of command line to apply the configs... I will work about it. Btw I have googled, and it is a common/known issue for Fedora people... So I think I may solve it faster... Thanks for the sharing of files and problem. Im going to fix it. Even if at that point, we should test on Arch too...

  • Fedora 44 still doesn't have curl with HTTP/3 support and building from source is such a hassle, so I can't test it that easily. I guess we can hold off HTTP/3 in nginx for now.

As I said, for the moment, HTTP3 is (unfortunately) out of my possible scope.

  • From playing around for a bit, I think you should also allow the HEAD method, curl -I is useful for testing HTTP without seeing the big responses.

We may add it in the description, cause not all people are able to do such activities. What do you think?

  • I think most of the security headers should go into the default configuration in Pi-hole, I am for avoiding extra headers in nginx (except HSTS).

Oh well, I will remove them 😉

@darkexplosiveqwx
Copy link
Copy Markdown
Contributor

  • From playing around for a bit, I think you should also allow the HEAD method, curl -I is useful for testing HTTP without seeing the big responses.

We may add it in the description, cause not all people are able to do such activities. What do you think?

I think we can just add HEAD to the list of allowed methods. Its considered a safe HTTP method, as it doesn't change server state, functionally it is just GET but without the body. I don't want to make it complicated.

As I said, for the moment, HTTP3 is (unfortunately) out of my possible scope.

Yes, I agree on not doing HTTP/3 here.

@DoctorD90
Copy link
Copy Markdown
Author

  • I think it would be difficult to to tell a user how to make the default fedora install usable, since the main ngnix.conf already has a server block.

Solved 😂 I have removed completely those commands ahahah .... I leave those level of action to the user. If they dont know how to enable/disable a site, it is better they dont use a Reverse Proxy but directly Pi-hole.

I think we can just add HEAD to the list of allowed methods.

Personally Im usually against leaving HEAD open, cause it is always used during attacks, cause it is handled in a different way from GET, but I have added it cause this isn't a guide to harden with the target to expose Pi-hole on Internet, so I'm easy going; I havent to be too much strict.

As per feedback in the relative Pull Request:
- Standardized SSL/TLS terminology;
- Removed the ACL and restart Pi-hole commands;
- Removed Headers already handled by Pi-hole;
- Added HEAD as allowed HTTP Method;
- Rework Nginx commands to resolve cross-distro configuration differences.
@darkexplosiveqwx
Copy link
Copy Markdown
Contributor

I think I'm satisfied with the overall shape we worked out, I'll comment on the code now for some continued small improvements.

Comment thread docs/guides/reverse_proxy/nginx.md Outdated
Comment thread docs/guides/reverse_proxy/nginx.md Outdated
- Restricting access via VPN or IP whitelisting;
- etc

**Disclaimer:** Utilizing `Nginx` as a reverse proxy does not automatically guarantee safety against all vulnerabilities associated with internet exposure. This guide focuses exclusively on the generic configuration of `Nginx` as a web proxy with some security tips; it does not cover, nor is it intended to cover, the advanced hardening techniques required for public internet exposure. Neither this guide nor the Pi-hole team shall be held responsible for any security breaches, data loss, or damages resulting from your network configuration.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This liability disclaimer sounds a bit to strong for me, I'd like to get the opinion of someone else @pi-hole/docs-maintainers.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should in general not suggest that it is a good idea to expose Pi-hole to the internet. No matter if behind reverse proxy or not.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Too Strong? .... I placed it especially to cover any possible issue and to underline how exposing the service to internet is a thing that should be done ONLY under the right knowledge... but well, on this point, you guys have green light for me whatever you decide 😊 edit as you wish

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if this phrasing would be good, this is why I checked in

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Too Strong? .... I placed it especially to cover any possible issue and to underline how exposing the service to internet is a thing that should be done ONLY under the right knowledge... but well, on this point, you guys have green light for me whatever you decide 😊 edit as you wish

I was more referring to the "absolutely no liability" part, of which I was unsure about.
The previous one about the dangers is reasonable.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was more referring to the "absolutely no liability" part, of which I was unsure about.
The previous one about the dangers is reasonable.

Belong to me, it isnt in any case ("by design") team's accountability for anything done or consequences produced by the software improperly used. This phrase is just merely "repeating"/"underling" something really objectives.
If "my" (AI-revised ahah) english wasnt good, I tried to just discourage people to expose it on internet and (if they do), this guide doesnt cover this scenario - it is up to them; this was my target.
Sorry in case Im misunderstanding you.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was comparing it to the warning at https://docs.pi-hole.net/ftldns/interfaces/. Neither exposing port 53 nor 80/443/whatever HTTP(S) is recommended. In my eyes "Neither this guide nor the Pi-hole team shall be held responsible for any security breaches, data loss, or damages resulting from your network configuration." sounds a bit overly defensive, but I am not quite sure on how to proceed. That's why I wanted to get another opinion here.


2. **Create the proxy file configuration**

Place the following file in your `Nginx` configuration path (e.g., `/etc/nginx/conf.d/` or `/etc/nginx/sites-available/` depending on your distribution configuration).
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it'd be useful to tell the user to look for potential port conflicts in server blocks already existing in /etc/nginx/conf, /etc/nginx/conf.d/ and /etc/nginx/sites-available/. Both with Pi-hole and other running services.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For this topic, I have tried to forecast the possibility and adopted the port 8080 in the config, to prevent possible conflicts for the port 80.
To be honest, I think that this should go a bit under each person custom scenarios. Especially for that I wrote in the Network Mapping & Port Alignment section which port the guide would use, and place attention to it, change according to personal setup.
At the start I wrote the guide as copy/paste, but thanks to your feedback, I rework it as "guidance"; as we said before in the previous interactions, if a person doesn't know what Nginx is or how to configure it, it is way better to use standard Pi-hole feature. This is a "guidance" for people that have knowledge of Nginx and are looking for a "pre-made" base for the Reverse Proxy.
Pi-hole v5 Nginx reverse proxy was a bit more complex due to fastcgi and php... but know it is way easier; I have find out many post, but most of the time, same questions: redirect api? redirect only admin? and so on. So I think we may do not focus extremely too much, because if they skip (important) section of the guide, we can't really repeat 10 times all the sections again... this is my personal point of view.

In case of a fresh install, it is up to the user to configure it wisely. Otherwise it is just used for.... ? In the "marketing phrase" we have removed I tried to underlined how Nginx is just not to be used as "Im cool guy, I have a reverse proxy", cause it adds nothing more than what Pi-hole (v6 especially) already provides. The team did an amazing job improving the internal http web server. Im to give support to test "new technologies", but not so much to "copy/paste" and forget... I wrote sections about possible issues in case of others pre-existing directives, using also "default Nginx value", just because lower value (in custom environment) may break and requires troubleshooting (as I had to do - in a customized nginx environment). So Im not really sure about this point 🤔 (just because I spammed already of warning everywhere in each dedicated sections 😂 it is becoming a warning spam, more than guide for how much I tried to underline to pay attention ahahah)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thinking more about "To avoid conflicts with Nginx or other services running on your system, we need to move Pi-hole v6 away from the standard HTTP port (80).", I guess its fine like this.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe a native speaker @PromoFaux can give an opinion?


1. **Create the redirect file configuration**

Place the following file in your Nginx configuration path (e.g., `/etc/nginx/conf.d/` or `/etc/nginx/sites-available/` depending on your distribution configuration).
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I copy/pasted to be consistent in the wording, but is the same thought of before 🤔

Explicit how long 63072000s actually are

Co-authored-by: darkexplosiveqwx <101737077+darkexplosiveqwx@users.noreply.github.com>
Signed-off-by: DoctorD90 <DoctorD90@users.noreply.github.com>
Comment thread docs/guides/reverse_proxy/nginx.md Outdated
It has been agreed to not affect other subdomains the user might have.

Co-authored-by: darkexplosiveqwx <101737077+darkexplosiveqwx@users.noreply.github.com>
Co-authored-by: DoctorD90 <DoctorD90@users.noreply.github.com>
Signed-off-by: DoctorD90 <DoctorD90@users.noreply.github.com>
@rdwebdesign rdwebdesign requested a review from PromoFaux May 15, 2026 16:22
Copy link
Copy Markdown
Contributor

@darkexplosiveqwx darkexplosiveqwx left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Those are spelling/grammar/wording fixes.
Please wait until confirmation from @PromoFaux before applying.


### Update Pi-hole's Configs

You must instruct Pi-hole to stop listening on port 80, 443 or any other ports and switch to our (arbitrary choosen) port **8053**. Additionally, for sake of security, we will restrict its web interface to listen only on the local interface (`127.0.0.1`), ensuring it is only accessible via the `Nginx` proxy.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You must instruct Pi-hole to stop listening on port 80, 443 or any other ports and switch to our (arbitrary choosen) port **8053**. Additionally, for sake of security, we will restrict its web interface to listen only on the local interface (`127.0.0.1`), ensuring it is only accessible via the `Nginx` proxy.
You must instruct Pi-hole to stop listening on port 80, 443 or any other ports and switch to our (arbitrarily chosen) port **8053**. Additionally, for sake of security, we will restrict its web interface to listen only on the local interface (`127.0.0.1`), ensuring it is only accessible via the `Nginx` proxy.

```

3. **Generate the Client Certificate**
We generate the private key for the user and a Certificate Signing Request (CSR). In real world, we should send the generated CSR to the CA for the signing, getting back the Certificate; in this guide (at command #3), and in Private PKI environments, we autonomusly sign it with our Private CA.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
We generate the private key for the user and a Certificate Signing Request (CSR). In real world, we should send the generated CSR to the CA for the signing, getting back the Certificate; in this guide (at command #3), and in Private PKI environments, we autonomusly sign it with our Private CA.
We generate the private key for the user and a Certificate Signing Request (CSR). In the real world, we should send the generated CSR to the CA for the signing, getting back the Certificate; in this guide (at command #3), and in Private PKI environments, we autonomously sign it with our Private CA.


1. **Generate the required Pi-hole SSL/TLS files**

We generate the private key and a Certificate Signing Request (CSR). In real world, we should send the generated CSR to the CA for the signing, getting back the Certificate; in this guide (at command #4) we directly self-sign them, or in a Private PKI environments, we autonomusly sign it with the Private CA.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
We generate the private key and a Certificate Signing Request (CSR). In real world, we should send the generated CSR to the CA for the signing, getting back the Certificate; in this guide (at command #4) we directly self-sign them, or in a Private PKI environments, we autonomusly sign it with the Private CA.
We generate the private key and a Certificate Signing Request (CSR). In the real world, we should send the generated CSR to the CA for the signing, getting back the Certificate; in this guide (at command #4) we directly self-sign them, or in a Private PKI environments, we autonomously sign it with the Private CA.


##### Security Headers

These header can add a layer of protection by instructing the user's browser how to handle the site's content securely:
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
These header can add a layer of protection by instructing the user's browser how to handle the site's content securely:
These headers can add a layer of protection by instructing the user's browser how to handle the site's content securely:

```

!!! danger "Change the PKCS#12 password"
In this guide, to speed up the command execution, the **weak** password `abcdef123456` has been used; we reccomend to choose a strong password and do not pass it via command line to keep it as secret as possible.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In this guide, to speed up the command execution, the **weak** password `abcdef123456` has been used; we reccomend to choose a strong password and do not pass it via command line to keep it as secret as possible.
In this guide, to speed up the command execution, the **weak** password `abcdef123456` has been used; we recommend to choose a strong password and do not pass it via command line to keep it as secret as possible.


!!! tip "TLS/SSL Installation"
- **Trust:** You may also need/want to import the `CertificateAuthority.pem` as a Trusted Root CA if it is a private one. Detailed instructions can be found in the [Pi-hole Official Documentation](/api/tls/#adding-the-ca-to-your-browser);
- **Browser:** Import the `client.p12` file into your browser's certificate manager (Settings > Security > Manage Certificates > Your Certificates); it is similar to precedent point, so you can read the [Pi-hole Official Documentation](/api/tls/#adding-the-ca-to-your-browser);
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- **Browser:** Import the `client.p12` file into your browser's certificate manager (Settings > Security > Manage Certificates > Your Certificates); it is similar to precedent point, so you can read the [Pi-hole Official Documentation](/api/tls/#adding-the-ca-to-your-browser);
- **Browser:** Import the `client.p12` file into your browser's certificate manager (Settings > Security > Manage Certificates > Your Certificates); it is similar to the previous point, so you can read the [Pi-hole Official Documentation](/api/tls/#adding-the-ca-to-your-browser);

@PromoFaux
Copy link
Copy Markdown
Member

I know I was only asked for my opinion as a native English speaker, and I appreciate that a lot of work has gone into creating and reviewing this PR however....

Honestly, this submission has "LLM-generated" written all over it, and I think we need to be honest about that before we consider merging it. I appreciate the acknowledgement that AI was used to assist with translation, but as a native speaker, I can tell the LLM has done considerably more than proofread the English, indeed it reads like it was generated, then lightly edited... not written and then polished.

The vast majority of this document is a general nginx and TLS tutorial wearing a Pi-hole "hat". The Pi-hole-specific content amounts to: change the port to 8053, bind to localhost.
The rest covers mTLS with a private CA, PKCS#12 exports, bcrypt cost factor tuning, cryptographic compatibility matrices, and browser certificate management.

A guide of this length and scope creates a maintenance burden, will go out of date, and frankly covers things that are already better documented elsewhere on the internet.


At the very most, I would expect a guide for this to be much shorter, focussed on what is unique to using the Pi-hole web interface behind nginx, with links to upstream documentation for everything else. Or, if you want to publish the entire thing in full - perhaps a personal blog is a better place for it.

But even then, that's pushing it. The guide has a big warning at the top of the doc is effectively saying "DON'T DO THIS", and then spends several thousand words explaining exactly how to do so in elaborate detail.

@darkexplosiveqwx
Copy link
Copy Markdown
Contributor

darkexplosiveqwx commented May 15, 2026

I know I was only asked for my opinion as a native English speaker, and I appreciate that a lot of work has gone into creating and reviewing this PR however....

Honestly, this submission has "LLM-generated" written all over it, and I think we need to be honest about that before we consider merging it. I appreciate the acknowledgement that AI was used to assist with translation, but as a native speaker, I can tell the LLM has done considerably more than proofread the English, indeed it reads like it was generated, then lightly edited... not written and then polished.

The vast majority of this document is a general nginx and TLS tutorial wearing a Pi-hole "hat". The Pi-hole-specific content amounts to: change the port to 8053, bind to localhost.

The rest covers mTLS with a private CA, PKCS#12 exports, bcrypt cost factor tuning, cryptographic compatibility matrices, and browser certificate management.

A guide of this length and scope creates a maintenance burden, will go out of date, and frankly covers things that are already better documented elsewhere on the internet.


At the very most, I would expect a guide for this to be much shorter, focussed on what is unique to using the Pi-hole web interface behind nginx, with links to upstream documentation for everything else. Or, if you want to publish the entire thing in full - perhaps a personal blog is a better place for it.

But even then, that's pushing it. The guide has a big warning at the top of the doc is effectively saying "DON'T DO THIS", and then spends several thousand words explaining exactly how to do so in elaborate detail.

About the AI and quality of the guide, I was also skeptical at first, maybe I got too involved now and tried to make it work?

I think I get your point, the DNS-related guides like Unbound add a good improvement on-top of Pi-hole's core functionality, DNS, and are more relevant.
Compare that to HTTP(S) where you can follow basically any guide and just replace the proxy target with localhost:piholehttpport. Since v6 has the embedded web server, there isn't anything crazy like php to think about, you can mostly treat Pi-hole as any other ol' web application.

For that the guide would be fairly simple and very modular: disable FTL's HTTPS, bind to 127.0.0.1:8085 and plug into any reverse proxy of your choice. We don't do any HTTP shenanigans, so there isn't really anything special.

Maybe some tips on how to setup the advanced webserver.paths.prefix would be nice, I struggled a bit when initially tried it out.

Edit:

Did't want to get too negative again, I'd consider this guide not that bad as a standalone, but I do think that we need to give our final goal with it another thought.

Edit2:

Regarding webserver.paths.prefix, I think that that option is fundamentally flawed and needs a rework. I've been thinking of creating a design proposal on this for quite some time, however nothing is ready yet, not even a starting point for discussion.

@PromoFaux
Copy link
Copy Markdown
Member

I'd consider this guide not that bad as a standalone

Indeed - the spirit of the guide is not bad overall (although I don't have the bandwidth to technically verify the content), this is just probably not the right home for it

@DoctorD90
Copy link
Copy Markdown
Author

but as a native speaker, I can tell the LLM has done considerably more than proofread the English, indeed it reads like it was generated, then lightly edited

Thanks @PromoFaux for your honest feedback. To be honest the only part that I "dont agree" is this one, cause I mainly write it in spaghetti-english with some part fastly written in my native language; instead of translating, I have prompted to follow the context provided and translate and fix, and, for sure, I have read again and again to be sure it was "as I would have written". I know many italian writers/blogger that after the AI era has been "accused" (not this situation, dont worry, I got your point) to use AI just cause they (human writers) used specific characters, or "sofism" that are largely abused but AI... but well, it is their own way of writing - and AI is trained also on those way of writing (Who came first? The egg or the chicken?). It is always so nice in 2026, release a text and end to discuss about the AI adoption 😅 ... What I may say is that I have reviewed it for over 1 week, and it is a bit frustrating as it is ending 😅

The guide has a big warning at the top of the doc is effectively saying "DON'T DO THIS", and then spends several thousand words explaining exactly how to do so in elaborate detail.

About that, the guide underlines to do not think "hey, this states it is secure! let's adopt it to expose over internet"... that was my intent and object. Sad it wasnt clear enough.

The Pi-hole-specific content amounts to: change the port to 8053, bind to localhost.

Yeah, I completely agree with you. I may have spend 10 mins (even without AI) to just drop the minimal configuration and stop, but I was moved by "hey! I use Pi-hole by years, let's try to give back my 5cent at the best I can", so I tried to cover all the topic that I have met on discourse/github/blogs/reddit/etc (problems, redirection, doubts, question about auth, misconfigurations) to provide a solid point of start to all the questions I have faced/find out...In that way I hoped to "solve" many discussions with just link to the official docs. Yes, I agree, cause it is true, I have spend a large amount of time/text about security (cause I consider it really important and Im the type of person that dont like to say "that's the fish, eat it", but I prefer to spend time to explain why this config, and if you dont know it, how to further customize and what to avoid with pihole otherwise ... blabla). It wasnt intended to be just "mTLS, CA, general nginx"; I have spend a lot of text also about configurations that may raise conflicts with Pi-hole (thanks again to @darkexplosiveqwx about websockets for example), and how to solve specific issue connected to Pi-hole. So Im a bit frustrated that those points/parts werent so "clear".

That said, if you think that for "Nginx" would be way better the minimal config, and link to the upstream documentation... I dont see problems if this is the direction the team wants 😊 ... even because it is just a "removal of many - many - many block of text with just hyperlinks to some of the tab I have still opened... So if you think this would be better let me know, it is easy to apply :)

@DoctorD90
Copy link
Copy Markdown
Author

I'd consider this guide not that bad as a standalone

Indeed - the spirit of the guide is not bad overall (although I don't have the bandwidth to technically verify the content), this is just probably not the right home for it

Oh Ive read it just now. Or if you think, we may just deny the PR, no problem at all! Im moved by just the spirit of contributing to a nice projects I ve followed and used since its very own starts and I really like 😊

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants