Metadata-Version: 2.4
Name: certbot-dns-micetro
Version: 1.0.4
Summary: Certbot plugin for Micetro DNS authentication
Home-page: https://github.com/cedarville-university/certbot-dns-micetro
Author: Nat Biggs
Author-email: nbiggs112@cedarville.edu
License: Apache License 2.0
Project-URL: Bug Reports, https://github.com/cedarville-university/certbot-dns-micetro/issues
Project-URL: Source, https://github.com/cedarville-university/certbot-dns-micetro
Keywords: certbot micetro dns ssl certificate letsencrypt
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Plugins
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: certbot>=1.1.0
Requires-Dist: zope.interface
Requires-Dist: requests>=2.20.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Certbot DNS Micetro Plugin

A certbot plugin for automating DNS-01 challenges using the BlueCat Micetro DNS management system.

[![Upload Python Package](https://github.com/cedarville-university/certbot-dns-micetro/actions/workflows/pypi.yml/badge.svg)](https://github.com/cedarville-university/certbot-dns-micetro/actions/workflows/pypi.yml)

## Features

- Automatic DNS TXT record creation and cleanup for ACME challenges
- Support for wildcard certificates
- Secure credential management via INI files
- Preference for external DNS zones over internal zones
- Comprehensive logging and error handling

## Installation

### From PyPI

```bash
pip install certbot-dns-micetro
```

### From Source

```bash
git clone https://github.com/cedarville-university/certbot-dns-micetro.git
cd certbot-dns-micetro
pip install .
```

## Configuration

Create a credentials INI file with your Micetro API details:

```ini
# micetro.ini
# Micetro API credentials for certbot DNS authentication
# Save this file with restricted permissions: chmod 600 micetro.ini

# Username for your Micetro account
dns_micetro_username = your_micetro_username

# Password for your Micetro account  
dns_micetro_password = your_micetro_password

# Micetro API base URL (include the protocol and port if needed)
# Example: https://ipam.yourcompany.com/mmws/api/v2
dns_micetro_url = https://your-micetro-server/mmws/api/v2

# DNS view to use for record management (optional)
# If not set, the default view will be used
dns_micetro_view = external
```

**Important:** Secure your credentials file:
```bash
chmod 600 micetro.ini
```

## Usage

### Obtain a certificate

```bash
certbot certonly \
  --authenticator dns-micetro \
  --dns-micetro-credentials /path/to/micetro.ini \
  -d example.com
```

### Obtain a wildcard certificate

```bash
certbot certonly \
  --authenticator dns-micetro \
  --dns-micetro-credentials /path/to/micetro.ini \
  -d example.com \
  -d "*.example.com"
```

### Certificate renewal

Certificates obtained with this plugin will be automatically renewed by certbot using the same DNS challenge method.

## API Requirements

This plugin requires:
- Micetro DNS management system with API access
- Valid user account with DNS zone management permissions
- Network connectivity to the Micetro API endpoint

The plugin authenticates using username/password credentials and obtains a session token from the `/sessions` endpoint.

## Zone Selection

When multiple DNS zones exist for the same domain (e.g., internal and external views), this plugin will:
1. Prefer external zones over internal zones
2. Use the first available zone if no external zone is found

## Troubleshooting

### Authentication Issues

- Verify your credentials in the INI file
- Ensure the Micetro API URL is correct and accessible
- Check that your user account has appropriate permissions

### DNS Issues

- Verify that the domain's DNS zone is managed by Micetro
- Ensure the zone allows dynamic DNS updates
- Check network connectivity to the Micetro server

### Debugging

Enable debug logging to troubleshoot issues:

Set environment variable with `export CERTBOT_DNS_MICETRO_DEBUG=1` for detailed API request/response logging
or use the `--debug` flag with certbot:
```bash
certbot certonly \
  --authenticator certbot-dns-micetro:dns-micetro \
  --certbot-dns-micetro:dns-micetro-credentials /path/to/micetro.ini \
  -d example.com \
  --debug
```

## Development

### Setting up development environment

```bash
git clone https://github.com/cedarville-university/certbot-dns-micetro.git
cd certbot-dns-micetro
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .
pip install -r requirements.txt
```

### Running tests

```bash
python -m pytest tests/
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Built on the [certbot](https://certbot.eff.org/) framework
- Designed for [BlueCat Micetro](https://www.bluecatnetworks.com/) DNS management
- Inspired by other certbot DNS plugins

## Support

For issues and questions:
- Open an issue on [GitHub](https://github.com/cedarville-university/certbot-dns-micetro/issues)
- Check the certbot documentation for general SSL certificate help
