Metadata-Version: 2.4
Name: certbot-dns-poweradmin
Version: 0.2.2
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 :: 3 - Alpha
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: pyopenssl>=26.0.0
Requires-Dist: requests>=2.33.1
Requires-Dist: urllib3>=2.6.0
Provides-Extra: dev
Requires-Dist: mypy>=1.13.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'
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.0 | 4.1.0+ | >= 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 supports both API v1 and v2.

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`. Set it to `v1` if your PowerAdmin installation uses the older API.

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

- Verify your API URL is correct and accessible
- 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
