{"id":1413,"library":"certbot-dns-cloudflare","title":"Certbot Cloudflare DNS Authenticator","description":"The `certbot-dns-cloudflare` plugin provides a DNS authenticator for Certbot, allowing you to obtain Let's Encrypt certificates using Cloudflare's DNS API. This is particularly useful for wildcard certificates. It is part of the larger Certbot project, currently at version 5.5.0, with minor releases typically aligned with Certbot's bimonthly schedule.","status":"active","version":"5.5.0","language":"en","source_language":"en","source_url":"https://github.com/certbot/certbot","tags":["certbot","cloudflare","dns","ssl","tls","authenticator","letsencrypt","cli"],"install":[{"cmd":"pip install certbot certbot-dns-cloudflare","lang":"bash","label":"Install with pip"},{"cmd":"sudo snap install certbot --classic\nsudo snap set certbot trust-plugin-with-root=ok\nsudo snap install certbot-dns-cloudflare","lang":"bash","label":"Install with Snap (recommended for production)"}],"dependencies":[{"reason":"This package is a plugin for Certbot and requires Certbot to be installed.","package":"certbot"}],"imports":[{"symbol":"certbot-dns-cloudflare","correct":"This plugin is used via the `certbot` command-line tool, not typically imported in Python code directly by end-users. Its functionality is exposed via CLI flags like `--dns-cloudflare`."}],"quickstart":{"code":"import os\nimport subprocess\nimport tempfile\nimport stat\n\n# --- Configuration for your domain and Cloudflare ---\nDOMAIN = \"yourdomain.com\" # Replace with your actual domain\nEMAIL = \"your@email.com\"  # Replace with your actual email\n\n# --- Cloudflare API Token (recommended) ---\n# For production, ensure this token has Zone DNS Write permissions for your domain.\n# Generate it at: https://dash.cloudflare.com/profile/api-tokens\n# Set this as an environment variable: export CLOUDFLARE_API_TOKEN=\"YOUR_TOKEN\"\nCLOUDFLARE_API_TOKEN = os.environ.get('CLOUDFLARE_API_TOKEN', 'YOUR_PLACEHOLDER_TOKEN')\n\nif CLOUDFLARE_API_TOKEN == 'YOUR_PLACEHOLDER_TOKEN':\n    print(\"WARNING: CLOUDFLARE_API_TOKEN environment variable not set. Using a placeholder.\")\n    print(\"         This quickstart will likely fail without a valid token.\")\n    print(\"         Set it using: export CLOUDFLARE_API_TOKEN=\\\"<YOUR_TOKEN>\\\"\")\n\n# --- Create a temporary credentials file ---\n# This file will store your Cloudflare API token securely.\n# Certbot requires this file to have restricted permissions (read-only for owner).\ntemp_dir = tempfile.mkdtemp()\ncredentials_path = os.path.join(temp_dir, 'cloudflare.ini')\n\ntry:\n    with open(credentials_path, 'w') as f:\n        f.write(f\"dns_cloudflare_api_token = {CLOUDFLARE_API_TOKEN}\\n\")\n    # Set permissions: owner read-only (0o400)\n    os.chmod(credentials_path, stat.S_IRUSR)\n    print(f\"Created temporary credentials file: {credentials_path}\")\n\n    # --- Construct and run the Certbot command ---\n    # This command obtains a certificate for your domain(s) using Cloudflare DNS.\n    # --dns-cloudflare-propagation-seconds: Adjust if DNS changes are slow to propagate.\n    # --test-cert: Use for testing to avoid hitting Let's Encrypt rate limits. Remove for production.\n    certbot_command = [\n        \"certbot\",\n        \"certonly\",\n        \"--dns-cloudflare\",\n        f\"--dns-cloudflare-credentials={credentials_path}\",\n        \"--dns-cloudflare-propagation-seconds\", \"60\",\n        \"-d\", DOMAIN,\n        \"-d\", f\"*.{DOMAIN}\", # Uncomment if you need a wildcard certificate\n        \"--email\", EMAIL,\n        \"--agree-tos\",\n        \"--non-interactive\",\n        \"--keep-until-expiring\",\n        \"--test-cert\" # IMPORTANT: Use this for initial testing! Remove for actual certificate issuance.\n    ]\n\n    print(\"\\nAttempting to run Certbot command:\")\n    print(f\"$ {' '.join(certbot_command)}\")\n\n    # Execute the command\n    result = subprocess.run(certbot_command, capture_output=True, text=True, check=False) # check=False to capture output on error\n\n    print(\"\\n--- Certbot Output ---\")\n    print(result.stdout)\n    if result.stderr:\n        print(\"\\n--- Certbot Errors ---\")\n        print(result.stderr)\n\n    if result.returncode == 0:\n        print(\"\\nSUCCESS: Certbot command completed. Check output for certificate path.\")\n    else:\n        print(f\"\\nFAILURE: Certbot command exited with code {result.returncode}.\")\n        print(\"Please review the output above, ensure your Cloudflare API token is valid and has correct permissions, and that your domain is managed by Cloudflare.\")\n\nexcept FileNotFoundError:\n    print(\"\\nERROR: 'certbot' command not found. Please ensure Certbot is installed and in your PATH.\")\n    print(\"       (e.g., pip install certbot certbot-dns-cloudflare or snap install certbot --classic)\")\nexcept Exception as e:\n    print(f\"\\nAn unexpected Python error occurred: {e}\")\nfinally:\n    # --- Clean up temporary files ---\n    if os.path.exists(credentials_path):\n        os.remove(credentials_path)\n        print(f\"\\nRemoved temporary credentials file: {credentials_path}\")\n    if os.path.exists(temp_dir):\n        os.rmdir(temp_dir)\n        print(f\"Removed temporary directory: {temp_dir}\")\n","lang":"python","description":"This quickstart script demonstrates how to obtain a certificate for your domain(s) using Certbot and the `certbot-dns-cloudflare` plugin. It creates a temporary credentials file for your Cloudflare API token (read from `CLOUDFLARE_API_TOKEN` environment variable for security) and then executes the `certbot` command. Remember to replace `yourdomain.com` and `your@email.com` with your actual details, and set the `CLOUDFLARE_API_TOKEN` environment variable. Use `--test-cert` for initial testing."},"warnings":[{"fix":"Upgrade your Python installation to 3.10 or later. Consider using a `snap` installation of Certbot, which bundles its own compatible Python environment, to avoid system Python conflicts.","message":"Certbot 5.0.0 and subsequent versions (including certbot-dns-cloudflare 5.x.x) require Python 3.10 or newer. Users on older Python versions will need to upgrade their Python environment.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"After creating your `cloudflare.ini` file, set its permissions using `chmod 400 /path/to/cloudflare.ini`. The quickstart code handles this automatically for the temporary file.","message":"The credentials file containing your Cloudflare API token/key must have restricted permissions (owner read-only, e.g., `0o400`) to prevent unauthorized access. Certbot will refuse to use files with broader permissions.","severity":"gotcha","affected_versions":"All"},{"fix":"Generate a dedicated API Token at Cloudflare Dashboard > My Profile > API Tokens. Use `dns_cloudflare_api_token = YOUR_TOKEN` in your credentials file. Avoid using your Global API Key (`dns_cloudflare_email` and `dns_cloudflare_api_key`) unless absolutely necessary.","message":"Cloudflare recommends using API Tokens (granular permissions) over Global API Keys (full account access). While the plugin supports both, API Tokens are more secure and should be preferred. Ensure the token has 'Zone DNS' 'Edit' permissions for the specific zones you intend to manage.","severity":"gotcha","affected_versions":"All"},{"fix":"Increase the propagation delay using the `--dns-cloudflare-propagation-seconds` flag, e.g., `--dns-cloudflare-propagation-seconds 60` or `120`. Monitor DNS changes with tools like `dig` to determine an appropriate value.","message":"DNS changes need time to propagate across the internet. If Certbot fails with a 'DNS problem' error, it might be due to insufficient propagation time. The default `30` seconds might not always be enough.","severity":"gotcha","affected_versions":"All"},{"fix":"For most users, especially on Linux, the `snap` installation (`sudo snap install certbot --classic`) is recommended as it's self-contained and handles dependencies. If using `pip`, ensure Certbot and its plugins are installed in the same virtual environment and that the `certbot` command points to that environment.","message":"Managing Certbot installations can be complex due to various methods (pip, snap, OS package managers). Mixing methods or using an outdated Certbot installation can lead to plugin not found errors or dependency conflicts.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}