0
# Certbot-nginx
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: certbot-nginx
7
- **Package Type**: Python plugin
8
- **Language**: Python
9
- **Installation**: `pip install certbot-nginx`
10
- **Plugin Name**: nginx (used with `certbot --nginx`)
11

12
## Core Imports
13

14
```python
15
from certbot_nginx._internal.configurator import NginxConfigurator
16
```
17

18
For parsing nginx configurations:
19

20
```python
21
from certbot_nginx._internal.parser import NginxParser
22
from certbot_nginx._internal.obj import VirtualHost, Addr
23
```
24

25
For low-level nginx config parsing:
26

27
```python
28
from certbot_nginx._internal import nginxparser
29
```
30

31
For platform constants and configuration:
32

33
```python
34
from certbot_nginx._internal import constants
35
```
36

37
For display operations:
38

39
```python
40
from certbot_nginx._internal.display_ops import select_vhost_multiple
41
```
42

43
## Basic Usage
44

45
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.
46

47
### Command Line Usage
48

49
```bash
50
# Obtain and install certificate with nginx plugin
51
certbot --nginx -d example.com
52

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

56
# Test nginx configuration changes
57
certbot --nginx --nginx-ctl nginx -d example.com
58
```
59

60
### Programmatic Usage
61

62
```python
63
from certbot_nginx._internal.configurator import NginxConfigurator
64
from certbot.configuration import NamespaceConfig
65

66
# Create configurator instance
67
config = NamespaceConfig()
68
configurator = NginxConfigurator(config, name='nginx')
69

70
# Prepare the configurator
71
configurator.prepare()
72

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

76
# Deploy certificate to domain
77
configurator.deploy_cert(
78
    domain='example.com',
79
    cert_path='/path/to/cert.pem',
80
    key_path='/path/to/key.pem', 
81
    chain_path='/path/to/chain.pem',
82
    fullchain_path='/path/to/fullchain.pem'
83
)
84

85
# Save configuration changes
86
configurator.save("Certificate installation")
87
```
88

89
## Architecture
90

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

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

100
## Capabilities
101

102
### Main Configurator
103

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

106
```python { .api }
107
class NginxConfigurator:
108
    description: str = "Nginx Web Server plugin"
109
    DEFAULT_LISTEN_PORT: str = '80'
110
    SSL_DIRECTIVES: list[str] = ['ssl_certificate', 'ssl_certificate_key', 'ssl_dhparam']
111
    
112
    def prepare(self) -> None: ...
113
    def deploy_cert(self, domain: str, cert_path: str, key_path: str, 
114
                   chain_path: str, fullchain_path: str) -> None: ...
115
    def choose_vhosts(self, target_name: str, create_if_no_match: bool = False) -> list[VirtualHost]: ...
116
    def enhance(self, domain: str, enhancement: str, options: str | list[str] | None = None) -> None: ...
117
    def get_all_names(self) -> set[str]: ...
118
```
119

120
[Main Configurator](./configurator.md)
121

122
### Configuration Parser
123

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

126
```python { .api }
127
class NginxParser:
128
    def load(self) -> None: ...
129
    def get_vhosts(self) -> list[VirtualHost]: ...
130
    def duplicate_vhost(self, vhost: VirtualHost, **kwargs) -> VirtualHost: ...
131
    def add_server_directives(self, vhost: VirtualHost, directives: list[list[str]], **kwargs) -> None: ...
132
    def update_or_add_server_directives(self, vhost: VirtualHost, directives: list[list[str]]) -> None: ...
133
```
134

135
[Configuration Parser](./parser.md)
136

137
### Virtual Host Objects
138

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

141
```python { .api }
142
class VirtualHost:
143
    filep: str
144
    addrs: Sequence[Addr]
145
    names: set[str]
146
    ssl: bool
147
    enabled: bool
148
    
149
    def contains_list(self, test_list: list[Any]) -> bool: ...
150
    def has_header(self, header_substring: str) -> bool: ...
151

152
class Addr:
153
    ssl: bool
154
    default: bool
155
    ipv6: bool
156
    ipv6only: bool
157
    
158
    @classmethod
159
    def fromstring(cls, str_addr: str) -> "Addr": ...
160
    def to_string(self, include_default: bool = True) -> str: ...
161
```
162

163
[Virtual Host Objects](./objects.md)
164

165
### HTTP-01 Challenge Handler
166

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

169
```python { .api }
170
class NginxHttp01:
171
    def perform(self) -> list[KeyAuthorizationChallengeResponse]: ...
172
    def add_chall(self, achall: KeyAuthorizationAnnotatedChallenge, index: int) -> None: ...
173
```
174

175
[HTTP-01 Challenge Handler](./http-01.md)
176

177
### Low-level Configuration Parser  
178

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

181
```python { .api }
182
class RawNginxParser:
183
    def parse(self) -> ParseResults: ...
184
    def as_list(self) -> list[Any]: ...
185

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

190
def load(source: str | IO[str]) -> UnspacedList: ...
191
def loads(source: str) -> UnspacedList: ...  
192
def dump(parsed_obj: UnspacedList, output: IO[str]) -> None: ...
193
def dumps(parsed_obj: UnspacedList) -> str: ...
194
```
195

196
[Low-level Parser](./nginxparser.md)
197

198
### Platform Constants and Configuration
199

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

202
```python { .api }
203
CLI_DEFAULTS: dict[str, Any] = {
204
    "server_root": str,
205
    "ctl": "nginx", 
206
    "sleep_seconds": 1
207
}
208

209
def os_constant(key: str) -> Any: ...
210
```
211

212
[Platform Constants](./constants.md)
213

214
### Display Operations
215

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

218
```python { .api }
219
def select_vhost_multiple(vhosts: Optional[Iterable[VirtualHost]]) -> list[VirtualHost]: ...
220
```
221

222
[Display Operations](./display-ops.md)
223

224
## Types
225

226
```python { .api }
227
from typing import Any, Sequence, Optional, Union, Iterable, Callable, IO, SupportsIndex
228
from acme.challenges import KeyAuthorizationChallengeResponse, Challenge
229
from certbot.achallenges import KeyAuthorizationAnnotatedChallenge
230
from certbot import errors
231
from certbot.plugins.common import Configurator, ChallengePerformer
232
from certbot.plugins.common import Addr as CommonAddr
233
from pyparsing import ParseResults
234
from certbot_nginx._internal.nginxparser import UnspacedList
235
```