certbot-dns-valuedomain

ValueDomain 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 ValueDomain API.

日本語ドキュメント

Features

• ✅ Automatic DNS-01 challenge completion
• ✅ Support for wildcard certificates
• ✅ Automatic TXT record cleanup
• ✅ Retry logic with exponential backoff
• ✅ Rate limit handling
• ✅ Comprehensive error handling
• ✅ Secure credential management

Installation

From PyPI (Recommended)

pip install certbot-dns-valuedomain

From Source

git clone https://github.com/chrono-meter/certbot-dns-valuedomain.git
cd certbot-dns-valuedomain
pip install -e .

Prerequisites

• Python 3.9 or higher
• Certbot 1.1.0 or higher
• ValueDomain account with API access
• Domain managed by ValueDomain

Python Version Support

Configuration

Named Arguments

Credentials File

Create a credentials file with your ValueDomain API information:

# ValueDomain API credentials
dns_valuedomain_api_key = your_api_key_here
dns_valuedomain_domain = example.com

The path to this file can be provided using the --dns-valuedomain-credentials command-line argument.

Security Best Practices

Important: Protect your credentials file with appropriate permissions:

chmod 600 /path/to/valuedomain.ini

Recommended location: ~/.secrets/certbot/valuedomain.ini

Usage Examples

Obtain a Certificate

certbot certonly 
  --authenticator dns-valuedomain 
  --dns-valuedomain-credentials ~/.secrets/certbot/valuedomain.ini 
  -d example.com

Obtain a Wildcard Certificate

certbot certonly 
  --authenticator dns-valuedomain 
  --dns-valuedomain-credentials ~/.secrets/certbot/valuedomain.ini 
  -d example.com 
  -d '*.example.com'

Obtain a Certificate with Custom Propagation Time

If you experience DNS propagation issues, increase the wait time:

certbot certonly 
  --authenticator dns-valuedomain 
  --dns-valuedomain-credentials ~/.secrets/certbot/valuedomain.ini 
  --dns-valuedomain-propagation-seconds 120 
  -d example.com

Renew Certificates

certbot renew 
  --authenticator dns-valuedomain 
  --dns-valuedomain-credentials ~/.secrets/certbot/valuedomain.ini

Automatic Renewal with Cron

Add to your crontab (crontab -e):

# Renew certificates daily at midnight
0 0 * * * certbot renew --authenticator dns-valuedomain --dns-valuedomain-credentials ~/.secrets/certbot/valuedomain.ini --quiet

Or use systemd timer (recommended for modern systems):

# Enable certbot timer
systemctl enable --now certbot-renew.timer

Test Certificate Issuance (Dry Run)

certbot certonly --dry-run 
  --authenticator dns-valuedomain 
  --dns-valuedomain-credentials ~/.secrets/certbot/valuedomain.ini 
  -d example.com

Getting ValueDomain API Key

1. Log in to ValueDomain
2. Navigate to your account settings
3. Go to API settings section
4. Generate a new API key
5. Copy the API key to your credentials file
6. Ensure your domain is properly configured in ValueDomain

ValueDomain API

This plugin uses the ValueDomain REST API v1:

• Get DNS records: GET /domains/{domain}/dns
• Set DNS records: PUT /domains/{domain}/dns

API Documentation: https://www.value-domain.com/api/doc/domain/

Authentication

The plugin uses Bearer token authentication:

Authorization: Bearer YOUR_API_KEY

Troubleshooting

DNS Propagation Errors

If you encounter DNS propagation timeout errors:

# Increase propagation wait time
--dns-valuedomain-propagation-seconds 120

API Authentication Errors

Error: API authentication failed

Solutions:

• Verify your API key is correct and active
• Check that the domain is managed by your ValueDomain account
• Ensure the credentials file has correct permissions (chmod 600)
• Verify the credentials file path is correct

Permission Denied Errors

Error: Permission denied when reading credentials

Solution:

chmod 600 ~/.secrets/certbot/valuedomain.ini

Rate Limit Errors

The plugin automatically handles rate limits with exponential backoff. If you consistently hit rate limits, consider:

• Reducing the frequency of certificate requests
• Contacting ValueDomain support to increase your API limits

Debug Mode

For detailed error information, use the --debug flag:

certbot certonly --debug 
  --authenticator dns-valuedomain 
  --dns-valuedomain-credentials ~/.secrets/certbot/valuedomain.ini 
  -d example.com

Common Issues

Issue: "Plugin not found"

# Reinstall the plugin
pip uninstall certbot-dns-valuedomain
pip install certbot-dns-valuedomain

Issue: "Invalid credentials format"

Ensure your credentials file follows this format:

dns_valuedomain_api_key = your_key
dns_valuedomain_domain = example.com

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/chrono-meter/certbot-dns-valuedomain.git
cd certbot-dns-valuedomain

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venvScriptsactivate

# Install development dependencies
pip install -r requirements-dev.txt

# Install in editable mode
pip install -e .

Run Tests

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=certbot_dns_valuedomain --cov-report=html

# View coverage report
open htmlcov/index.html

Code Quality

# Format code
black certbot_dns_valuedomain tests

# Lint code
flake8 certbot_dns_valuedomain tests

# Type checking
mypy certbot_dns_valuedomain --ignore-missing-imports

Running Tests Before Commit

# Run all checks
black certbot_dns_valuedomain tests && 
flake8 certbot_dns_valuedomain tests && 
pytest tests/ --cov=certbot_dns_valuedomain

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Contribution Guidelines

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (pytest tests/)
6. Format your code (black .)
7. Commit your changes (git commit -m 'Add some amazing feature')
8. Push to the branch (git push origin feature/amazing-feature)
9. Open a Pull Request

Code Style

• Follow PEP 8 guidelines
• Use Black for code formatting
• Add type hints where applicable
• Write comprehensive docstrings
• Include unit tests for new features

Security

Reporting Security Issues

If you discover a security vulnerability, please email the maintainer directly instead of using the issue tracker.

Security Best Practices

• Never commit credentials to version control
• Use strict file permissions (600) for credentials files
• Rotate API keys regularly
• Use environment-specific credentials
• Review logs for sensitive information leakage

License

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

Support

• Issues: GitHub Issues
• Documentation: GitHub Wiki
• Discussions: GitHub Discussions

Acknowledgments

• Certbot - The Let's Encrypt client
• ValueDomain - DNS provider
• All contributors to this project

Related Projects

• Certbot - Official Certbot client
• certbot-dns-cloudflare - Cloudflare DNS plugin
• certbot-dns-route53 - Route53 DNS plugin

Changelog

See CHANGELOG.md for a list of changes in each version.

Author

chrono-meter stz2012

Project Status

This project is actively maintained. Issues and pull requests are regularly reviewed.

Note: This plugin is not officially affiliated with ValueDomain or Let's Encrypt.