From ce36c9d98d15d17b079504b1b1be20ed026f71df Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Tue, 4 Feb 2025 16:40:24 +0100 Subject: [PATCH 01/11] add tls and basic http auth guide --- docs/.vuepress/config.js | 1 + docs/how-to/kubo-tls.md | 103 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 104 insertions(+) create mode 100644 docs/how-to/kubo-tls.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index b2f7b4978..f852e5dec 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -207,6 +207,7 @@ module.exports = { '/how-to/command-line-quick-start', '/how-to/configure-node', '/how-to/modify-bootstrap-list', + '/how-to/kubo-tls', '/how-to/nat-configuration', '/how-to/ipfs-updater', [ diff --git a/docs/how-to/kubo-tls.md b/docs/how-to/kubo-tls.md new file mode 100644 index 000000000..4b4c38b11 --- /dev/null +++ b/docs/how-to/kubo-tls.md @@ -0,0 +1,103 @@ +--- +title: TLS and HTTP Auth for Kubo +description: Learn how to set up TLS and basic HTTP auth for Kubo with Caddy reverse proxy for secure API access over public networks. +--- + +# Setting up TLS and basic HTTP auth for Kubo with Caddy reverse proxy + +This guide will help you set up two things: + +- **Transport Encryption:** Caddy as a reverse proxy with automatic TLS certificate management for your Kubo node. +- **Authentication:** Basic HTTP auth for the Kubo RPC API. + +This is highly recommended if you run your own Kubo node and want to use the Kubo RPC API over public networks, for example, to pin data from CI, or other services. Since the Kubo RPC API is exposed over plain HTTP, you will need to use TLS to ensure the connection to the API is encrypted. + +## Prerequisites + +Before starting, ensure you have: + +- A domain name (referred to as `YOUR_DOMAIN`) with its A record pointing to your server's IP address +- Kubo running on a server/VM with a public IP address +- Port 443 open on your server's firewall +- [Caddy web server](https://caddyserver.com/) installed on the server + +## Configure Kubo + +First, you'll need to configure Kubo to work with the reverse proxy. Edit your Kubo config file (usually located at `~/.ipfs/config`) and update the API section: + +``` +"API": { + "HTTPHeaders": { + "Access-Control-Allow-Origin": ["https://YOUR_DOMAIN"], + "Access-Control-Allow-Credentials": ["true"] + }, + "Authorizations": { + "api": { + "AuthSecret": "basic:hello:world123" + "AllowedPaths": [ + "/api/v0" + ] + } + } +} +``` + +This configuration: + +- Sets CORS headers to allow requests from `YOUR_DOMAIN`. Kubo will match the `host` header in the request with the `Access-Control-Allow-Origin` from the configuration, so you need to ensure the origin is correct. +- Restricts API access to the Kubo RPC API, allowing access to the `/api/v0` endpoints with basic http authentication. + +> **Note:** You should set the `AuthSecret` to a stronger username and password combination. + +## Configure Caddy + +Create or edit your Caddyfile (typically at `/etc/caddy/Caddyfile`) with the following configuration, making sure to replace `YOUR_DOMAIN` with your actual domain name: + +``` +YOUR_DOMAIN { + reverse_proxy localhost:5001 + + log { + output stdout + format json + level INFO + } +} +``` + +This configuration: + +- Sets up a reverse proxy to Kubo's API on port 5001 +- Logs requests to the Kubo API in JSON format to stdout + +## Restart Caddy + +```bash +sudo systemctl restart caddy +``` + +## Test the Connection + +To verify everything is working correctly, test the connection using the IPFS CLI: + +```bash +ipfs id --api /dns/YOUR_DOMAIN/tcp/443/https --api-auth basic:hello:world123 +``` + +If successful, you should see your node's information displayed. The command connects to your Kubo node through the secure HTTPS endpoint using basic authentication. + +## Security Considerations + +- Change the `AuthSecret` to a strong username and password combination +- Consider restricting the `AllowedPaths` further based on your needs +- Keep your Caddy and Kubo installations updated +- Regularly monitor the logs for any suspicious activity + +## Troubleshooting + +If you encounter issues: + +1. Check Caddy logs +2. Verify your domain's DNS settings, ensuring the A record is correct +3. Ensure port 443 is open and not blocked by your firewall +4. Check that Kubo is running and accessible on localhost:5001 From 03f6e4495bcac123e103b664781d62e9b2454137 Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Tue, 4 Feb 2025 16:42:16 +0100 Subject: [PATCH 02/11] chore: add caddy to allowed names --- .github/styles/pln-ignore.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/styles/pln-ignore.txt b/.github/styles/pln-ignore.txt index 27093865f..c515b321a 100644 --- a/.github/styles/pln-ignore.txt +++ b/.github/styles/pln-ignore.txt @@ -22,6 +22,7 @@ bool(ean) boolean boxo browserify +caddy callout callouts cas From 627d89b636216615bc1f4ff596eae6b647f899ae Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Tue, 4 Feb 2025 16:44:40 +0100 Subject: [PATCH 03/11] fix: typo --- docs/how-to/kubo-tls.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how-to/kubo-tls.md b/docs/how-to/kubo-tls.md index 4b4c38b11..fed423e9a 100644 --- a/docs/how-to/kubo-tls.md +++ b/docs/how-to/kubo-tls.md @@ -1,6 +1,6 @@ --- title: TLS and HTTP Auth for Kubo -description: Learn how to set up TLS and basic HTTP auth for Kubo with Caddy reverse proxy for secure API access over public networks. +description: Learn how to set up TLS for Kubo with Caddy reverse proxy for secure API access over public networks. --- # Setting up TLS and basic HTTP auth for Kubo with Caddy reverse proxy @@ -45,7 +45,7 @@ First, you'll need to configure Kubo to work with the reverse proxy. Edit your K This configuration: - Sets CORS headers to allow requests from `YOUR_DOMAIN`. Kubo will match the `host` header in the request with the `Access-Control-Allow-Origin` from the configuration, so you need to ensure the origin is correct. -- Restricts API access to the Kubo RPC API, allowing access to the `/api/v0` endpoints with basic http authentication. +- Restricts API access to the Kubo RPC API, allowing access to the `/api/v0` endpoints with basic HTTP authentication. > **Note:** You should set the `AuthSecret` to a stronger username and password combination. From 5e5892a1479851b4fd6e1832e93e176f897be20b Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Mon, 10 Feb 2025 15:41:29 +0100 Subject: [PATCH 04/11] docs: refinemets --- docs/how-to/kubo-tls.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/how-to/kubo-tls.md b/docs/how-to/kubo-tls.md index fed423e9a..2025ab920 100644 --- a/docs/how-to/kubo-tls.md +++ b/docs/how-to/kubo-tls.md @@ -3,14 +3,14 @@ title: TLS and HTTP Auth for Kubo description: Learn how to set up TLS for Kubo with Caddy reverse proxy for secure API access over public networks. --- -# Setting up TLS and basic HTTP auth for Kubo with Caddy reverse proxy +# Setting up TLS and HTTP authentication for Kubo with Caddy reverse proxy This guide will help you set up two things: -- **Transport Encryption:** Caddy as a reverse proxy with automatic TLS certificate management for your Kubo node. -- **Authentication:** Basic HTTP auth for the Kubo RPC API. +- **Transport Encryption:** Caddy as a reverse proxy with automatic TLS certificate management for your Kubo node using a domain you control. +- **Authentication:** Basic HTTP authentication for the Kubo RPC API. -This is highly recommended if you run your own Kubo node and want to use the Kubo RPC API over public networks, for example, to pin data from CI, or other services. Since the Kubo RPC API is exposed over plain HTTP, you will need to use TLS to ensure the connection to the API is encrypted. +This is highly recommended if you run your own Kubo node and want to use the Kubo RPC API over public networks, for example, to pin CIDs from CI, or other services. Since the Kubo RPC API is exposed over plain HTTP, TLS is used to ensure the connection to the API is encrypted. ## Prerequisites @@ -21,6 +21,8 @@ Before starting, ensure you have: - Port 443 open on your server's firewall - [Caddy web server](https://caddyserver.com/) installed on the server +The guide assumes the Caddy process is managed by systemd. If you are using a different process manager or Docker, you will need to adjust the configuration accordingly. + ## Configure Kubo First, you'll need to configure Kubo to work with the reverse proxy. Edit your Kubo config file (usually located at `~/.ipfs/config`) and update the API section: @@ -72,19 +74,21 @@ This configuration: ## Restart Caddy +Restart the Caddy service to apply the changes: + ```bash sudo systemctl restart caddy ``` ## Test the Connection -To verify everything is working correctly, test the connection using the IPFS CLI: +To verify everything is working correctly, test the connection using the IPFS CLI, making sure to replace `YOUR_DOMAIN` with your actual domain name: ```bash ipfs id --api /dns/YOUR_DOMAIN/tcp/443/https --api-auth basic:hello:world123 ``` -If successful, you should see your node's information displayed. The command connects to your Kubo node through the secure HTTPS endpoint using basic authentication. +If successful, you should see your node's identify displayed. The command connects to your Kubo node through the secure HTTPS endpoint using basic authentication. ## Security Considerations @@ -98,6 +102,6 @@ If successful, you should see your node's information displayed. The command con If you encounter issues: 1. Check Caddy logs -2. Verify your domain's DNS settings, ensuring the A record is correct +2. Verify your domain's DNS settings, ensuring the A record is correct. Sometimes changes can take a few minutes to propagate (depending on the TTL of the DNS record). 3. Ensure port 443 is open and not blocked by your firewall 4. Check that Kubo is running and accessible on localhost:5001 From 10975485efce7c02c8b503bbbc15eb09203cdd1c Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Mon, 10 Feb 2025 16:15:24 +0100 Subject: [PATCH 05/11] chore: update permalink --- docs/.vuepress/config.js | 2 +- docs/how-to/{kubo-tls.md => kubo-tls-auth.md} | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) rename docs/how-to/{kubo-tls.md => kubo-tls-auth.md} (98%) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index f852e5dec..635bd4f92 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -207,7 +207,7 @@ module.exports = { '/how-to/command-line-quick-start', '/how-to/configure-node', '/how-to/modify-bootstrap-list', - '/how-to/kubo-tls', + '/how-to/kubo-tls-auth', '/how-to/nat-configuration', '/how-to/ipfs-updater', [ diff --git a/docs/how-to/kubo-tls.md b/docs/how-to/kubo-tls-auth.md similarity index 98% rename from docs/how-to/kubo-tls.md rename to docs/how-to/kubo-tls-auth.md index 2025ab920..d109746f5 100644 --- a/docs/how-to/kubo-tls.md +++ b/docs/how-to/kubo-tls-auth.md @@ -1,5 +1,5 @@ --- -title: TLS and HTTP Auth for Kubo +title: TLS and HTTP Auth for Kubo with Caddy description: Learn how to set up TLS for Kubo with Caddy reverse proxy for secure API access over public networks. --- From 3370781ef68db2dad0f5547b9426f7dd8e0537e1 Mon Sep 17 00:00:00 2001 From: Daniel N <2color@users.noreply.github.com> Date: Mon, 10 Feb 2025 16:34:25 +0100 Subject: [PATCH 06/11] add link to guide from rpc docs --- tools/http-api-docs/markdown.go | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tools/http-api-docs/markdown.go b/tools/http-api-docs/markdown.go index 14b3e3c20..2a70e5c05 100644 --- a/tools/http-api-docs/markdown.go +++ b/tools/http-api-docs/markdown.go @@ -82,6 +82,8 @@ The RPC API provides admin-level access to your Kubo IPFS node, including `+"`/a It is bound to `+"`localhost`"+` by default on purpose. You should never expose it to the public internet, just like you would never expose a SQL database or other backend service. +To expose the RPC API to the public internet with TLS encryption and HTTP authentication, check out the [TLS and HTTP Auth for Kubo with Caddy](../../how-to/kubo-tls-auth.md) guide. + If you are looking for an interface designed for browsers and public internet, consider implementation-agnostic [HTTP Gateway](../../reference/http/gateway.md) instead. ::: From 1bd73ece72092c9af65ae8a822c1ea56c260616a Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Tue, 11 Feb 2025 02:48:00 +0100 Subject: [PATCH 07/11] nit: include rpc in url slug avoiding confusion between gateway and rpc --- .github/styles/pln-ignore.txt | 3 +++ docs/.vuepress/config.js | 2 +- docs/how-to/{kubo-tls-auth.md => kubo-rpc-tls-auth.md} | 8 ++++---- 3 files changed, 8 insertions(+), 5 deletions(-) rename docs/how-to/{kubo-tls-auth.md => kubo-rpc-tls-auth.md} (92%) diff --git a/.github/styles/pln-ignore.txt b/.github/styles/pln-ignore.txt index c515b321a..18387f1a0 100644 --- a/.github/styles/pln-ignore.txt +++ b/.github/styles/pln-ignore.txt @@ -23,6 +23,7 @@ boolean boxo browserify caddy +Caddyfile callout callouts cas @@ -115,6 +116,7 @@ keepalive keypair keystores kubo +Kubo's kubuxu laika lan @@ -214,6 +216,7 @@ Someguy subcommand substring sys +systemd sztandera testground testnet diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 635bd4f92..31630e7f2 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -207,7 +207,7 @@ module.exports = { '/how-to/command-line-quick-start', '/how-to/configure-node', '/how-to/modify-bootstrap-list', - '/how-to/kubo-tls-auth', + '/how-to/kubo-rpc-tls-auth', '/how-to/nat-configuration', '/how-to/ipfs-updater', [ diff --git a/docs/how-to/kubo-tls-auth.md b/docs/how-to/kubo-rpc-tls-auth.md similarity index 92% rename from docs/how-to/kubo-tls-auth.md rename to docs/how-to/kubo-rpc-tls-auth.md index d109746f5..0cb067044 100644 --- a/docs/how-to/kubo-tls-auth.md +++ b/docs/how-to/kubo-rpc-tls-auth.md @@ -1,14 +1,14 @@ --- -title: TLS and HTTP Auth for Kubo with Caddy -description: Learn how to set up TLS for Kubo with Caddy reverse proxy for secure API access over public networks. +title: TLS and HTTP Auth for Kubo RPC with Caddy +description: Learn how to set up TLS for Kubo with Caddy reverse proxy for secure RPC API access over public networks. --- -# Setting up TLS and HTTP authentication for Kubo with Caddy reverse proxy +# Setting up TLS and HTTP authentication for Kubo RPC with Caddy reverse proxy This guide will help you set up two things: - **Transport Encryption:** Caddy as a reverse proxy with automatic TLS certificate management for your Kubo node using a domain you control. -- **Authentication:** Basic HTTP authentication for the Kubo RPC API. +- **Authentication:** Basic HTTP authentication for the [Kubo RPC API](../reference/kubo/rpc.md). This is highly recommended if you run your own Kubo node and want to use the Kubo RPC API over public networks, for example, to pin CIDs from CI, or other services. Since the Kubo RPC API is exposed over plain HTTP, TLS is used to ensure the connection to the API is encrypted. From b025d1e54fa135db56d4e2b0f2116cf5d494e823 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Tue, 11 Feb 2025 02:56:51 +0100 Subject: [PATCH 08/11] test: regenerate rpc docs --- docs/reference/kubo/rpc.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/reference/kubo/rpc.md b/docs/reference/kubo/rpc.md index 86a4ac328..1df8becdc 100644 --- a/docs/reference/kubo/rpc.md +++ b/docs/reference/kubo/rpc.md @@ -47,7 +47,7 @@ I AM SERIOUS, DO NOT EDIT ANYTHING BELOW ;-D --> -::: tip Generated on 2025-01-29, from kubo v0.33.0 +::: tip Generated on 2025-02-11, from kubo v0.33.0 This document was autogenerated from [v0.33.0](https://github.com/ipfs/kubo/releases/tag/v0.33.0). For issues and support, check out the [http-api-docs](https://github.com/ipfs/ipfs-docs/tree/main/tools/http-api-docs) generator on GitHub. ::: @@ -62,6 +62,8 @@ The RPC API provides admin-level access to your Kubo IPFS node, including `/api/ It is bound to `localhost` by default on purpose. You should never expose it to the public internet, just like you would never expose a SQL database or other backend service. +To expose the RPC API to the public internet with TLS encryption and HTTP authentication, check out the [TLS and HTTP Auth for Kubo with Caddy](../../how-to/kubo-tls-auth.md) guide. + If you are looking for an interface designed for browsers and public internet, consider implementation-agnostic [HTTP Gateway](../../reference/http/gateway.md) instead. ::: From 923abe0c0c948e4c58263100720673456b1bd5cf Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Tue, 11 Feb 2025 03:00:29 +0100 Subject: [PATCH 09/11] fix link and lint --- docs/reference/kubo/rpc.md | 2 +- tools/http-api-docs/markdown.go | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/kubo/rpc.md b/docs/reference/kubo/rpc.md index 564ad541d..9678b328d 100644 --- a/docs/reference/kubo/rpc.md +++ b/docs/reference/kubo/rpc.md @@ -62,7 +62,7 @@ The RPC API provides admin-level access to your Kubo IPFS node, including `/api/ It is bound to `localhost` by default on purpose. You should never expose it to the public internet, just like you would never expose a SQL database or other backend service. -To expose the RPC API to the public internet with TLS encryption and HTTP authentication, check out the [TLS and HTTP Auth for Kubo with Caddy](../../how-to/kubo-tls-auth.md) guide. +To expose the RPC API to the public internet with TLS encryption and HTTP authentication, check out the [TLS and HTTP Auth for Kubo with Caddy](../../how-to/kubo-rpc-tls-auth.md) guide. If you are looking for an interface designed for browsers and public internet, consider implementation-agnostic [HTTP Gateway](../../reference/http/gateway.md) instead. ::: diff --git a/tools/http-api-docs/markdown.go b/tools/http-api-docs/markdown.go index 2a70e5c05..d97e2afa9 100644 --- a/tools/http-api-docs/markdown.go +++ b/tools/http-api-docs/markdown.go @@ -82,7 +82,7 @@ The RPC API provides admin-level access to your Kubo IPFS node, including `+"`/a It is bound to `+"`localhost`"+` by default on purpose. You should never expose it to the public internet, just like you would never expose a SQL database or other backend service. -To expose the RPC API to the public internet with TLS encryption and HTTP authentication, check out the [TLS and HTTP Auth for Kubo with Caddy](../../how-to/kubo-tls-auth.md) guide. +To expose the RPC API to the public internet with TLS encryption and HTTP authentication, check out the [TLS and HTTP Auth for Kubo with Caddy](../../how-to/kubo-rpc-tls-auth.md) guide. If you are looking for an interface designed for browsers and public internet, consider implementation-agnostic [HTTP Gateway](../../reference/http/gateway.md) instead. ::: From b78370d3b236e905dccf469332c235b7fe6aacba Mon Sep 17 00:00:00 2001 From: Daniel Norman <1992255+2color@users.noreply.github.com> Date: Tue, 11 Feb 2025 12:17:13 +0100 Subject: [PATCH 10/11] Apply suggestions from code review Co-authored-by: Marcin Rataj --- docs/.vuepress/config.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 31630e7f2..c7a053296 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -207,8 +207,8 @@ module.exports = { '/how-to/command-line-quick-start', '/how-to/configure-node', '/how-to/modify-bootstrap-list', - '/how-to/kubo-rpc-tls-auth', '/how-to/nat-configuration', + '/how-to/kubo-rpc-tls-auth', '/how-to/ipfs-updater', [ 'https://github.com/ipfs-examples/js-ipfs-examples/tree/master/examples/custom-ipfs-repo', From 10177f79683e25fd7eb106e16dbcbf01eb1ba516 Mon Sep 17 00:00:00 2001 From: Daniel Norman <1992255+2color@users.noreply.github.com> Date: Tue, 11 Feb 2025 12:24:20 +0100 Subject: [PATCH 11/11] Apply suggestions from code review --- docs/how-to/kubo-rpc-tls-auth.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how-to/kubo-rpc-tls-auth.md b/docs/how-to/kubo-rpc-tls-auth.md index 0cb067044..55f29dad7 100644 --- a/docs/how-to/kubo-rpc-tls-auth.md +++ b/docs/how-to/kubo-rpc-tls-auth.md @@ -1,9 +1,9 @@ --- -title: TLS and HTTP Auth for Kubo RPC with Caddy +title: Secure Kubo RPC with TLS and HTTP Auth description: Learn how to set up TLS for Kubo with Caddy reverse proxy for secure RPC API access over public networks. --- -# Setting up TLS and HTTP authentication for Kubo RPC with Caddy reverse proxy +# Secure Kubo RPC with TLS and HTTP Auth This guide will help you set up two things: