[GH-ISSUE #71] sync README with config, perhaps better docs about ips #27

New issue

Open

opened 2026-03-13 15:24:26 +03:00 by kerem · 3 comments

kerem commented

2026-03-13 15:24:26 +03:00

Owner

Originally created by @jvanasco on GitHub (Apr 10, 2018).
Original GitHub issue: https://github.com/acme-dns/acme-dns/issues/71

The readme and config differ a bit

For example, the README shows

# listen ip, default "" listens on all interfaces/addresses
ip = "127.0.0.1"

But the config was changed to be:

listen ip eg. 127.0.0.1

ip = "0.0.0.0"

i'm sure multiple default elements were changed - that's the only one I noticed from my limited knowledge of the library. the content of the README installation guide should reflect the current config options/defaults and docstrings.

In terms of docs about ips... defaulting to 127.0.0.1 is probably safest, as as it will only work from the same machine (or require a proxy on the machine) since there are not access controls in place- but many people will likely want to use 0.0.0.0 for testing. was there a reason this was changed to 0.0.0.0?

https://raw.githubusercontent.com/joohoi/acme-dns/3343d943d604be8bc0ab0830bccfb6459d1ae95c/README.md#L230-L240

https://github.com/joohoi/acme-dns/blob/master/config.cfg#L34-L39

Originally created by @jvanasco on GitHub (Apr 10, 2018). Original GitHub issue: https://github.com/acme-dns/acme-dns/issues/71 The readme and config differ a bit For example, the README shows # listen ip, default "" listens on all interfaces/addresses ip = "127.0.0.1" But the config was changed to be: # listen ip eg. 127.0.0.1 ip = "0.0.0.0" i'm sure multiple default elements were changed - that's the only one I noticed from my limited knowledge of the library. the content of the README installation guide should reflect the current config options/defaults and docstrings. In terms of docs about ips... defaulting to `127.0.0.1` is probably safest, as as it will only work from the same machine (or require a proxy on the machine) since there are not access controls in place- but many people will likely want to use `0.0.0.0` for testing. was there a reason this was changed to 0.0.0.0? https://raw.githubusercontent.com/joohoi/acme-dns/3343d943d604be8bc0ab0830bccfb6459d1ae95c/README.md#L230-L240 https://github.com/joohoi/acme-dns/blob/master/config.cfg#L34-L39

kerem added the

Documentation

label

2026-03-13 15:24:26 +03:00

kerem commented

2026-03-13 15:24:37 +03:00

Author

Owner

@joohoi commented on GitHub (Apr 12, 2018):

Thanks for opening the issue. I believe most people are binding the acme-dns to a public interface. Possible access control is done on a separate layer (firewall, reverse proxy etc). This is also the reason the default value was changed, the service is designed to being accessed by multiple clients across the network, so binding to localhost as default didn't make much sense.

This is based on the expectations this project was originally built on, the decision is in no way final, and I'm up for discussion about the matter.

The README should definitely be synced with the actual config values in the end.

@joohoi commented on GitHub (Apr 12, 2018): Thanks for opening the issue. I believe most people are binding the acme-dns to a public interface. Possible access control is done on a separate layer (firewall, reverse proxy etc). This is also the reason the default value was changed, the service is designed to being accessed by multiple clients across the network, so binding to localhost as default didn't make much sense. This is based on the expectations this project was originally built on, the decision is in no way final, and I'm up for discussion about the matter. The README should definitely be synced with the actual config values in the end.

kerem commented

2026-03-13 15:24:42 +03:00

Author

Owner

@jvanasco commented on GitHub (Apr 12, 2018):

The README should definitely be synced with the actual config values in the end.

This was the main motivation for this ticket.

I believe most people are binding the acme-dns to a public interface. Possible access control is done on a separate layer (firewall, reverse proxy etc). This is also the reason the default value was changed, the service is designed to being accessed by multiple clients across the network, so binding to localhost as default didn't make much sense.

I agree that's the common usage, and expected the change was for that. What I failed to convey is that my concern is over the docs in strings and narratives that correspond to IP configuration. A lot of people who use this are unlikely to know the difference between localhost and the public address, and the risks/requirements involved with each. Example, for a long time Redis defaulted to 0.0.0.0 - which many people didn't expect - and glossed over that line... which lead to many servers hacked. I got burned by that when doing an update, and have been very sensitive to default listen configs ever since.

so it might make sense to use the default config as..

# listen ip. eg: 127.0.0.1 for localhost only; 0.0.0.0 for all/public address
ip = "0.0.0.0"

or even

# listen ip. eg: "127.0.0.1" for localhost only; "0.0.0.0" for all/public address
# most users will want to listen on the public address "0.0.0.0" so outside clients can access.
# if your only clients are on this machine or you have firewall rules, "127.0.0.1" may be preferred.
ip = ""

@jvanasco commented on GitHub (Apr 12, 2018): > The README should definitely be synced with the actual config values in the end. This was the main motivation for this ticket. > I believe most people are binding the acme-dns to a public interface. Possible access control is done on a separate layer (firewall, reverse proxy etc). This is also the reason the default value was changed, the service is designed to being accessed by multiple clients across the network, so binding to localhost as default didn't make much sense. I agree that's the common usage, and expected the change was for that. What I failed to convey is that my concern is over the docs in strings and narratives that correspond to IP configuration. A lot of people who use this are unlikely to know the difference between localhost and the public address, and the risks/requirements involved with each. Example, for a long time Redis defaulted to `0.0.0.0` - which many people didn't expect - and glossed over that line... which lead to many servers hacked. I got burned by that when doing an update, and have been very sensitive to default listen configs ever since. so it might make sense to use the default config as.. # listen ip. eg: 127.0.0.1 for localhost only; 0.0.0.0 for all/public address ip = "0.0.0.0" or even # listen ip. eg: "127.0.0.1" for localhost only; "0.0.0.0" for all/public address # most users will want to listen on the public address "0.0.0.0" so outside clients can access. # if your only clients are on this machine or you have firewall rules, "127.0.0.1" may be preferred. ip = ""

kerem commented

2026-03-13 15:24:47 +03:00

Author

Owner

@joohoi commented on GitHub (Sep 28, 2018):

README.md is now pretty much up to sync with the config.cfg, the IP clarification is still pending.

@joohoi commented on GitHub (Sep 28, 2018): `README.md` is now pretty much up to sync with the `config.cfg`, the IP clarification is still pending.