From 54115deb85ff0500b0cc0fb0ba3f2d68e8973df5 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Wed, 27 Nov 2024 15:16:55 +0100 Subject: [PATCH 1/2] docs: document production Corefile it was missing acme section, and docs were also lacking context --- .gitignore | 1 + Corefile | 11 +++++++++++ README.md | 10 +++++----- 3 files changed, 17 insertions(+), 5 deletions(-) diff --git a/.gitignore b/.gitignore index f1552d3..ea8cc30 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ cmd/cmd p2p-forge p2p-forge-certs/ badger.libp2p-direct-challenges/ +registration_libp2p_direct-certs/ diff --git a/Corefile b/Corefile index e7008c5..5cd1028 100644 --- a/Corefile +++ b/Corefile @@ -5,4 +5,15 @@ libp2p.direct { prometheus localhost:9253 ipparser libp2p.direct file zones/libp2p.direct + acme libp2p.direct { + # HTTP API at /v1/_acme-challenge + # production settings: TLS is terminated elsewhere: + registration-domain registration.libp2p.direct listen-address=:80 external-tls=true + # to handle tls termination as well, use: listen-address=:443 external-tls=false + # + # DNS-01 challenge cache + # production settings: DynamoDB shared across all instances + database-type dynamo libp2p-direct-challenges + # for local dev with badger: database-type badger badger.libp2p-direct-challenges + } } diff --git a/README.md b/README.md index 5630616..93111a9 100644 --- a/README.md +++ b/README.md @@ -154,13 +154,13 @@ acme FORGE_DOMAIN { } ~~~ -- **FORGE_DOMAIN** the domain of the forge (e.g. libp2p.direct) -- **REGISTRATION_DOMAIN** the domain used by clients to send requests for setting ACME challenges (e.g. registration.libp2p.direct) +- **FORGE_DOMAIN** the domain suffix of the forge (e.g. `libp2p.direct`) +- **REGISTRATION_DOMAIN** the HTTP API domain used by clients to send requests for setting ACME challenges (e.g. `registration.libp2p.direct`) - **ADDRESS** is the address and port for the internal HTTP server to listen on (e.g. :1234), defaults to `:443`. - - external-tls should be set to true if the TLS termination (and validation of the registration domain name) will happen externally or should be handled locally, defaults to false + - `external-tls` should be set to `true` if the TLS termination (and validation of the registration domain name) will happen externally or should be handled locally, defaults to false - **DB_TYPE** is the type of the backing database used for storing the ACME challenges. Options include: - - dynamo TABLE_NAME (where all credentials are set via AWS' standard environment variables) - - badger DB_PATH + - `dynamo TABLE_NAME` for production-grade key-value store shared across multiple instances (where all credentials are set via AWS' standard environment variables: `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`) + - `badger DB_PATH` for local key-value store (good for local development and testing) ### Example From 231d5a34fd435038dbb32b780e3d1e63263c69b6 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Wed, 27 Nov 2024 15:28:11 +0100 Subject: [PATCH 2/2] docs: Corefile.local-dev documenting how to get started locally, saving an hour figuring it out --- .dockerignore | 2 ++ Corefile | 2 ++ Corefile.local-dev | 14 ++++++++++++++ README.md | 15 ++++++++++++--- 4 files changed, 30 insertions(+), 3 deletions(-) create mode 100644 Corefile.local-dev diff --git a/.dockerignore b/.dockerignore index 44b8fd0..867dd74 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,5 +1,7 @@ Corefile +Corefile.local-dev zones p2p-forge p2p-forge-certs/ badger.libp2p-direct-challenges/ +registration_libp2p_direct-certs/ diff --git a/Corefile b/Corefile index 5cd1028..734b78e 100644 --- a/Corefile +++ b/Corefile @@ -1,3 +1,5 @@ +# this file demonstrates reference production settings. +# for local development use: ./p2p-forge -conf Corefile.local-dev libp2p.direct { log errors diff --git a/Corefile.local-dev b/Corefile.local-dev new file mode 100644 index 0000000..62fb7c3 --- /dev/null +++ b/Corefile.local-dev @@ -0,0 +1,14 @@ +# for local development on ports 5354 (dns) and 5380 (http) +# run with: ./p2p-forge -conf Corefile.local-dev -dns.port 5354 +libp2p.direct { + log + errors + any # RFC 8482 + prometheus localhost:9253 + ipparser libp2p.direct + file zones/libp2p.direct + acme libp2p.direct { + registration-domain registration.libp2p.direct listen-address=:5380 external-tls=true + database-type badger badger.libp2p-direct-challenges + } +} diff --git a/README.md b/README.md index 93111a9..ea4481d 100644 --- a/README.md +++ b/README.md @@ -96,17 +96,26 @@ Will download using go mod, build and install the binary in your global Go binar ### Local testing -Build and run a custom Corefile configuration and on custom port: +Build and run a custom Corefile configuration and on custom ports (DNS port set to `5354` via CLI, HTTP port set to `5380` via custom Corefile): ```console -$ ./p2p-forge -conf Corefile.example -dns.port 5353 +$ ./p2p-forge -conf Corefile.local-dev -dns.port 5354 ``` Test with `dig`: ```console -$ dig A 1-2-3-4.k51qzi5uqu5dlwfht6wwy7lp4z35bgytksvp5sg53fdhcocmirjepowgifkxqd.libp2p.direct @localhost -p 5353 +$ dig A 1-2-3-4.k51qzi5uqu5dlwfht6wwy7lp4z35bgytksvp5sg53fdhcocmirjepowgifkxqd.libp2p.direct @localhost -p 5354 1.2.3.4 + +$ curl http://localhost:5380/v1/health -I +HTTP/1.1 204 No Content +``` + +To run on port `53` as non-root user, adjust permission: + +```console +$ sudo setcap cap_net_bind_service=+ep /path/to/p2p-forge ``` ### Docker