Metadata-Version: 2.5
Name: certbot-dns-poweradmin
Version: 0.2.7
Summary: PowerAdmin DNS Authenticator plugin for Certbot
Project-URL: Homepage, https://github.com/poweradmin/certbot-dns-poweradmin
Project-URL: Bug Reports, https://github.com/poweradmin/certbot-dns-poweradmin/issues
Project-URL: Source, https://github.com/poweradmin/certbot-dns-poweradmin
Author-email: Edmondas Girkantas <edmondas@girkantas.lt>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Requires-Dist: acme>=5.1.0
Requires-Dist: certbot>=5.1.0
Requires-Dist: requests>=2.33.1
Provides-Extra: dev
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: pyopenssl>=26.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: requests-mock>=1.11.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Requires-Dist: tox>=4.0.0; extra == 'dev'
Requires-Dist: types-requests>=2.32.0; extra == 'dev'
Requires-Dist: urllib3>=2.6.0; extra == 'dev'
Description-Content-Type: text/markdown

# certbot-dns-poweradmin

[![Test](https://github.com/poweradmin/certbot-dns-poweradmin/actions/workflows/test.yml/badge.svg)](https://github.com/poweradmin/certbot-dns-poweradmin/actions/workflows/test.yml)
[![codecov](https://codecov.io/gh/poweradmin/certbot-dns-poweradmin/graph/badge.svg?token=3686WTALGK)](https://codecov.io/gh/poweradmin/certbot-dns-poweradmin)
[![PyPI](https://img.shields.io/pypi/v/certbot-dns-poweradmin)](https://pypi.org/project/certbot-dns-poweradmin/)
[![Python](https://img.shields.io/pypi/pyversions/certbot-dns-poweradmin)](https://pypi.org/project/certbot-dns-poweradmin/)

PowerAdmin DNS Authenticator plugin for Certbot

This plugin automates the process of completing a `dns-01` challenge by creating, and subsequently removing, TXT records using the PowerAdmin API.

## Version Compatibility

| Plugin Version | Poweradmin Version | Python | Certbot |
|---|---|---|---|
| 0.2.x | 4.1.0 - 4.5.x | >= 3.10 | >= 5.1.0 |
| 0.1.x | 4.1.0 - 4.2.x | >= 3.10 | >= 5.1.0 |

## Installation

```
pip install certbot-dns-poweradmin
```

## PowerAdmin Configuration

Your PowerAdmin installation needs to have the API enabled. The plugin uses API v2 by default. API v1 is deprecated and was removed in Poweradmin 4.5.0.

You'll need an API key with permissions to:
- List zones
- Create DNS records
- Delete DNS records

## Usage

1. Create a credential file (e.g., `/etc/letsencrypt/poweradmin.ini`):

```ini
dns_poweradmin_api_url = https://poweradmin.example.com
dns_poweradmin_api_key = your-api-key-here
dns_poweradmin_api_version = v2
```

The `api_version` is optional and defaults to `v2`. Setting it to `v1` is deprecated: it works only with Poweradmin below 4.5.0, logs a warning, and will be removed in the next major release of this plugin. Poweradmin 4.5.0 and later answer `410 Gone` on every API v1 request, so use `v2` there.

2. Secure the credential file:

```
chmod 600 /etc/letsencrypt/poweradmin.ini
```

3. Run certbot:

```
certbot certonly \
  --authenticator dns-poweradmin \
  --dns-poweradmin-credentials /etc/letsencrypt/poweradmin.ini \
  -d example.com
```

## Arguments

| Argument                               | Description                                        |
|----------------------------------------|----------------------------------------------------|
| `--dns-poweradmin-credentials`         | Path to credentials INI file (required)            |
| `--dns-poweradmin-propagation-seconds` | Seconds to wait for DNS propagation (default: 120) |

## Examples

Get a certificate for a single domain:

```
certbot certonly \
  --authenticator dns-poweradmin \
  --dns-poweradmin-credentials /etc/letsencrypt/poweradmin.ini \
  -d example.com
```

Get a wildcard certificate:

```
certbot certonly \
  --authenticator dns-poweradmin \
  --dns-poweradmin-credentials /etc/letsencrypt/poweradmin.ini \
  -d example.com \
  -d "*.example.com"
```

With custom propagation time:

```
certbot certonly \
  --authenticator dns-poweradmin \
  --dns-poweradmin-credentials /etc/letsencrypt/poweradmin.ini \
  --dns-poweradmin-propagation-seconds 300 \
  -d example.com
```

## Docker

```dockerfile
FROM certbot/certbot
RUN pip install certbot-dns-poweradmin
```

Build and run:

```
docker build -t certbot/dns-poweradmin .

docker run --rm \
  -v /etc/letsencrypt:/etc/letsencrypt \
  -v /var/lib/letsencrypt:/var/lib/letsencrypt \
  certbot/dns-poweradmin certonly \
  --authenticator dns-poweradmin \
  --dns-poweradmin-credentials /etc/letsencrypt/poweradmin.ini \
  -d example.com
```

## Troubleshooting

### Plugin not found by certbot

If `certbot plugins` doesn't show `dns-poweradmin`, ensure both certbot and the plugin are installed in the same Python environment:

```bash
# Check where certbot is installed
which certbot

# If using system certbot but plugin in venv, either:
# Option 1: Install certbot in the same venv
pip install certbot certbot-dns-poweradmin

# Option 2: Use certbot from the venv
python -m certbot plugins
```

### Virtual environment usage

When using a virtual environment, install both certbot and the plugin together:

```bash
python3 -m venv certbot-env
source certbot-env/bin/activate
pip install certbot certbot-dns-poweradmin

# Run certbot from the venv
certbot plugins  # should show dns-poweradmin
```

### API connection issues

- Use the base URL of your PowerAdmin installation as `dns_poweradmin_api_url`
  (e.g. `https://poweradmin.example.com`), including the `https://` scheme and
  without the `/api` path — the plugin appends `/api/v1` or `/api/v2` itself
- The URL must not redirect (e.g. `http://` to `https://`); the plugin refuses
  redirects and asks you to configure the final URL directly
- Check that your API key has the required permissions

## Sponsors

<a href="https://www.stepping-stone.ch/">
  <img src=".github/stepping_stone_logo.svg" alt="stepping stone AG" height="60">
</a>

We thank [stepping stone AG](https://www.stepping-stone.ch/) for their support of this project.

## License

Apache License 2.0
