diff --git a/.github/styles/pln-ignore.txt b/.github/styles/pln-ignore.txt index 27093865f..18387f1a0 100644 --- a/.github/styles/pln-ignore.txt +++ b/.github/styles/pln-ignore.txt @@ -22,6 +22,8 @@ bool(ean) boolean boxo browserify +caddy +Caddyfile callout callouts cas @@ -114,6 +116,7 @@ keepalive keypair keystores kubo +Kubo's kubuxu laika lan @@ -213,6 +216,7 @@ Someguy subcommand substring sys +systemd sztandera testground testnet diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index b2f7b4978..c7a053296 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -208,6 +208,7 @@ module.exports = { '/how-to/configure-node', '/how-to/modify-bootstrap-list', '/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', diff --git a/docs/how-to/kubo-rpc-tls-auth.md b/docs/how-to/kubo-rpc-tls-auth.md new file mode 100644 index 000000000..55f29dad7 --- /dev/null +++ b/docs/how-to/kubo-rpc-tls-auth.md @@ -0,0 +1,107 @@ +--- +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. +--- + +# Secure Kubo RPC with TLS and HTTP Auth + +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](../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. + +## 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 + +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: + +``` +"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 + +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, 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 identify 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. 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 diff --git a/docs/reference/kubo/rpc.md b/docs/reference/kubo/rpc.md index 830f26c41..9678b328d 100644 --- a/docs/reference/kubo/rpc.md +++ b/docs/reference/kubo/rpc.md @@ -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-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 14b3e3c20..d97e2afa9 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-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. :::