tessl/pypi-certbot-nginx

Nginx plugin for Certbot that enables automated SSL/TLS certificate management and deployment for Nginx web servers.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Certbot-nginx

Name: tessl/pypi-certbot-nginx
Author: tessl

A Certbot plugin that provides automated SSL/TLS certificate management and deployment for Nginx web servers. It integrates with the Certbot ACME client to automatically configure Nginx virtual hosts for HTTPS, handle certificate installation and renewal, and manage SSL configuration directives.

Package Information

Package Name: certbot-nginx
Package Type: Python plugin
Language: Python
Installation: pip install certbot-nginx
Plugin Name: nginx (used with certbot --nginx)

Core Imports

from certbot_nginx._internal.configurator import NginxConfigurator

For parsing nginx configurations:

from certbot_nginx._internal.parser import NginxParser
from certbot_nginx._internal.obj import VirtualHost, Addr

For low-level nginx config parsing:

from certbot_nginx._internal import nginxparser

For platform constants and configuration:

from certbot_nginx._internal import constants

For display operations:

from certbot_nginx._internal.display_ops import select_vhost_multiple

Basic Usage

The certbot-nginx package is primarily designed to be used as a Certbot plugin, not as a standalone library. It's registered as the 'nginx' plugin in Certbot's plugin system.

Command Line Usage

# Obtain and install certificate with nginx plugin
certbot --nginx -d example.com

# Specify nginx server root
certbot --nginx --nginx-server-root /etc/nginx -d example.com

# Test nginx configuration changes
certbot --nginx --nginx-ctl nginx -d example.com

Programmatic Usage

from certbot_nginx._internal.configurator import NginxConfigurator
from certbot.configuration import NamespaceConfig

# Create configurator instance
config = NamespaceConfig()
configurator = NginxConfigurator(config, name='nginx')

# Prepare the configurator
configurator.prepare()

# Get all virtual hosts
vhosts = configurator.parser.get_vhosts()

# Deploy certificate to domain
configurator.deploy_cert(
    domain='example.com',
    cert_path='/path/to/cert.pem',
    key_path='/path/to/key.pem', 
    chain_path='/path/to/chain.pem',
    fullchain_path='/path/to/fullchain.pem'
)

# Save configuration changes
configurator.save("Certificate installation")

Architecture

The certbot-nginx plugin follows a modular architecture with clear separation of concerns:

NginxConfigurator: Main plugin class implementing Certbot's configurator interface
NginxParser: High-level nginx configuration parser and modifier
NginxHttp01: HTTP-01 challenge handler for ACME authentication
VirtualHost/Addr: Object models representing nginx server blocks and listen addresses
nginxparser: Low-level pyparsing-based nginx configuration parser
Constants: Platform-specific defaults and configuration values

Capabilities

Main Configurator

Core Certbot plugin functionality including certificate deployment, virtual host management, configuration testing, and nginx server control.

class NginxConfigurator:
    description: str = "Nginx Web Server plugin"
    DEFAULT_LISTEN_PORT: str = '80'
    SSL_DIRECTIVES: list[str] = ['ssl_certificate', 'ssl_certificate_key', 'ssl_dhparam']
    
    def prepare(self) -> None: ...
    def deploy_cert(self, domain: str, cert_path: str, key_path: str, 
                   chain_path: str, fullchain_path: str) -> None: ...
    def choose_vhosts(self, target_name: str, create_if_no_match: bool = False) -> list[VirtualHost]: ...
    def enhance(self, domain: str, enhancement: str, options: str | list[str] | None = None) -> None: ...
    def get_all_names(self) -> set[str]: ...

Main Configurator

Configuration Parser

Nginx configuration file parsing and modification capabilities with support for complex nginx configuration structures and included files.

class NginxParser:
    def load(self) -> None: ...
    def get_vhosts(self) -> list[VirtualHost]: ...
    def duplicate_vhost(self, vhost: VirtualHost, **kwargs) -> VirtualHost: ...
    def add_server_directives(self, vhost: VirtualHost, directives: list[list[str]], **kwargs) -> None: ...
    def update_or_add_server_directives(self, vhost: VirtualHost, directives: list[list[str]]) -> None: ...

Configuration Parser

Virtual Host Objects

Object models for representing nginx virtual hosts and network addresses with comprehensive attribute access and manipulation methods.

class VirtualHost:
    filep: str
    addrs: Sequence[Addr]
    names: set[str]
    ssl: bool
    enabled: bool
    
    def contains_list(self, test_list: list[Any]) -> bool: ...
    def has_header(self, header_substring: str) -> bool: ...

class Addr:
    ssl: bool
    default: bool
    ipv6: bool
    ipv6only: bool
    
    @classmethod
    def fromstring(cls, str_addr: str) -> "Addr": ...
    def to_string(self, include_default: bool = True) -> str: ...

Virtual Host Objects

HTTP-01 Challenge Handler

ACME HTTP-01 challenge implementation for nginx with automatic server block configuration and challenge response serving.

class NginxHttp01:
    def perform(self) -> list[KeyAuthorizationChallengeResponse]: ...
    def add_chall(self, achall: KeyAuthorizationAnnotatedChallenge, index: int) -> None: ...

HTTP-01 Challenge Handler

Low-level Configuration Parser

Pyparsing-based nginx configuration parser for raw configuration file manipulation with complete syntax support.

class RawNginxParser:
    def parse(self) -> ParseResults: ...
    def as_list(self) -> list[Any]: ...

class UnspacedList(list[Any]):
    def insert(self, i: SupportsIndex, x: Any) -> None: ...
    def append(self, x: Any) -> None: ...

def load(source: str | IO[str]) -> UnspacedList: ...
def loads(source: str) -> UnspacedList: ...  
def dump(parsed_obj: UnspacedList, output: IO[str]) -> None: ...
def dumps(parsed_obj: UnspacedList) -> str: ...

Low-level Parser

Platform Constants and Configuration

Platform-specific constants, configuration defaults, and SSL management values for cross-platform compatibility.

CLI_DEFAULTS: dict[str, Any] = {
    "server_root": str,
    "ctl": "nginx", 
    "sleep_seconds": 1
}

def os_constant(key: str) -> Any: ...

Platform Constants

Display Operations

Interactive user interface operations for virtual host selection and management when multiple options are available.

def select_vhost_multiple(vhosts: Optional[Iterable[VirtualHost]]) -> list[VirtualHost]: ...

Display Operations

Types

from typing import Any, Sequence, Optional, Union, Iterable, Callable, IO, SupportsIndex
from acme.challenges import KeyAuthorizationChallengeResponse, Challenge
from certbot.achallenges import KeyAuthorizationAnnotatedChallenge
from certbot import errors
from certbot.plugins.common import Configurator, ChallengePerformer
from certbot.plugins.common import Addr as CommonAddr
from pyparsing import ParseResults
from certbot_nginx._internal.nginxparser import UnspacedList

Install with Tessl CLI

npx tessl i tessl/pypi-certbot-nginx

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: about 1 month ago
Describes: pkg:pypi/certbot-nginx@5.0.x
Publish Source: CLI
Badge