Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

fix(ssl): resolve certbot outside $PATH and preflight the nginx plugin

Juan Denis81928ec7ff0c
diff --git a/backend/app/services/advanced_ssl_service.py b/backend/app/services/advanced_ssl_service.py
index f418a03d..93bd9b48 100644
--- a/backend/app/services/advanced_ssl_service.py
+++ b/backend/app/services/advanced_ssl_service.py
@@ -3,6 +3,12 @@ import logging
import subprocess
from datetime import datetime
from app.utils.system import run_command
+from app.services.ssl_service import resolve_certbot_bin
+
+
+def _certbot_bin():
+ """Resolved certbot binary, falling back to the bare name (PATH lookup)."""
+ return resolve_certbot_bin() or 'certbot'
logger = logging.getLogger(__name__)
@@ -47,7 +53,7 @@ class AdvancedSSLService:
from app.utils.system import PackageManager
wildcard = f'*.{domain}'
- cmd = ['certbot', 'certonly', '--non-interactive', '--agree-tos',
+ cmd = [_certbot_bin(), 'certonly', '--non-interactive', '--agree-tos',
'--dns-' + dns_provider, '-d', domain, '-d', wildcard]
cmd.extend(['--email', email] if email else ['--register-unsafely-without-email'])
@@ -89,7 +95,7 @@ class AdvancedSSLService:
if not domains or len(domains) < 1:
raise ValueError('At least one domain required')
- cmd = ['certbot', 'certonly', '--non-interactive', '--agree-tos',
+ cmd = [_certbot_bin(), 'certonly', '--non-interactive', '--agree-tos',
'--webroot', '-w', '/var/www/html']
for d in domains:
cmd.extend(['-d', d])
diff --git a/backend/app/services/ssl_service.py b/backend/app/services/ssl_service.py
index 65c2809d..18d216d0 100644
--- a/backend/app/services/ssl_service.py
+++ b/backend/app/services/ssl_service.py
@@ -1,4 +1,5 @@
import os
+import shutil
import subprocess
import json
from datetime import datetime
@@ -8,16 +9,71 @@ from pathlib import Path
from app.utils.system import ServiceControl, run_privileged, PackageManager, is_command_available
+# Candidate locations for the certbot binary when it isn't on $PATH. Snap is
+# certbot's recommended install method and lands in /snap/bin (often missing
+# from a service's $PATH); apt/dnf land in /usr/bin; pip installs land in
+# /usr/local/bin.
+_CERTBOT_CANDIDATES = ('/usr/bin/certbot', '/snap/bin/certbot', '/usr/local/bin/certbot')
+
+_certbot_bin_cache: Optional[str] = None
+
+
+def reset_certbot_resolution_cache() -> None:
+ """Drop the cached certbot path (tests, and right after installing certbot)."""
+ global _certbot_bin_cache
+ _certbot_bin_cache = None
+
+
+def resolve_certbot_bin() -> Optional[str]:
+ """Resolve the certbot binary path.
+
+ Resolution order: the ``CERTBOT_BIN`` environment override (honored
+ unconditionally), then ``shutil.which('certbot')``, then the well-known
+ candidate paths including the snap location. Returns ``None`` when
+ certbot cannot be found.
+
+ The result is cached — certbot's install location does not change
+ mid-process. Negative results are intentionally not cached so a later
+ install is picked up without a restart.
+ """
+ global _certbot_bin_cache
+ if _certbot_bin_cache is not None:
+ return _certbot_bin_cache
+
+ override = os.environ.get('CERTBOT_BIN')
+ if override:
+ _certbot_bin_cache = override
+ return _certbot_bin_cache
+
+ found = shutil.which('certbot')
+ if not found:
+ for candidate in _CERTBOT_CANDIDATES:
+ if os.path.isfile(candidate) and \
+ (os.name == 'nt' or os.access(candidate, os.X_OK)):
+ found = candidate
+ break
+
+ _certbot_bin_cache = found
+ return found
+
+
class SSLService:
"""Service for SSL certificate management with Let's Encrypt."""
- CERTBOT_BIN = os.environ.get('CERTBOT_BIN', '/usr/bin/certbot')
+ # Fallback used when resolution finds nothing, preserving the historical
+ # default; commands built with it fail cleanly with FileNotFoundError.
+ CERTBOT_FALLBACK = '/usr/bin/certbot'
CERTS_DIR = '/etc/letsencrypt/live'
RENEWAL_DIR = '/etc/letsencrypt/renewal'
# Custom-cert install location (e.g. issued Cloudflare Origin CA certs, written
# by AdvancedSSLService.upload_custom_cert). certbot doesn't know about these.
SERVERKIT_CERTS_DIR = '/etc/ssl/serverkit'
+ @classmethod
+ def certbot_bin(cls) -> str:
+ """Resolved certbot binary path (never ``None`` — see CERTBOT_FALLBACK)."""
+ return resolve_certbot_bin() or cls.CERTBOT_FALLBACK
+
@classmethod
def is_certbot_installed(cls) -> bool:
"""Check if certbot is installed."""
@@ -37,10 +93,57 @@ class SSLService:
if result.returncode != 0:
return {'success': False, 'error': result.stderr}
+ reset_certbot_resolution_cache()
return {'success': True, 'message': 'Certbot installed successfully'}
except Exception as e:
return {'success': False, 'error': str(e)}
+ @classmethod
+ def _has_nginx_plugin(cls, certbot: str) -> bool:
+ """Check certbot's plugin list for an enabled nginx plugin.
+
+ Parses ``certbot plugins`` output (authoritative for both apt and snap
+ installs; enabled plugins are listed as ``* nginx``, disabled as
+ ``- nginx``). Falls back to the distro package check when the probe
+ itself fails, so a broken ``plugins`` subcommand doesn't block issuance
+ on a host where the plugin package is clearly present.
+ """
+ try:
+ result = run_privileged([certbot, 'plugins'], timeout=60)
+ if result.returncode == 0:
+ return any(
+ line.strip().startswith('* nginx')
+ for line in (result.stdout or '').split('\n')
+ )
+ except Exception:
+ pass
+ return PackageManager.is_installed('python3-certbot-nginx')
+
+ @classmethod
+ def _preflight_nginx_plugin(cls, certbot: str) -> Optional[Dict]:
+ """Verify certbot's nginx plugin before invoking ``certbot --nginx``.
+
+ Without this, a host that has certbot but not the plugin (or a certbot
+ that can't see the nginx binary) fails deep inside certbot with a
+ confusing "nginx plugin is not working / binary doesn't exist" message
+ that we would pass through raw. Returns an actionable error dict, or
+ ``None`` when everything is in place.
+ """
+ if not is_command_available('nginx'):
+ return {
+ 'success': False,
+ 'error': 'nginx binary not found — install nginx before '
+ 'requesting a certificate with the nginx plugin',
+ }
+ if not cls._has_nginx_plugin(certbot):
+ return {
+ 'success': False,
+ 'error': 'certbot nginx plugin not installed — install '
+ 'python3-certbot-nginx (apt) or use the certbot snap, '
+ 'which bundles the nginx plugin',
+ }
+ return None
+
@classmethod
def obtain_certificate(cls, domains: List[str], email: str,
webroot_path: str = None, use_nginx: bool = True) -> Dict:
@@ -52,9 +155,12 @@ class SSLService:
try:
# Build certbot command
- cmd = [cls.CERTBOT_BIN, 'certonly']
+ cmd = [cls.certbot_bin(), 'certonly']
if use_nginx:
+ preflight_error = cls._preflight_nginx_plugin(cmd[0])
+ if preflight_error is not None:
+ return preflight_error
cmd.append('--nginx')
elif webroot_path:
cmd.extend(['--webroot', '-w', webroot_path])
@@ -111,7 +217,7 @@ class SSLService:
def renew_certificate(cls, domain: str = None) -> Dict:
"""Renew SSL certificate(s)."""
try:
- cmd = [cls.CERTBOT_BIN, 'renew', '--non-interactive']
+ cmd = [cls.certbot_bin(), 'renew', '--non-interactive']
if domain:
cmd.extend(['--cert-name', domain])
@@ -132,7 +238,7 @@ class SSLService:
try:
cmd = [
- cls.CERTBOT_BIN, 'revoke',
+ cls.certbot_bin(), 'revoke',
'--cert-path', cert_path,
'--non-interactive'
]
@@ -142,7 +248,7 @@ class SSLService:
if result.returncode == 0:
# Also delete the certificate
delete_cmd = [
- cls.CERTBOT_BIN, 'delete',
+ cls.certbot_bin(), 'delete',
'--cert-name', domain,
'--non-interactive'
]
@@ -160,7 +266,7 @@ class SSLService:
certificates = []
try:
- result = run_privileged([cls.CERTBOT_BIN, 'certificates'], timeout=60)
+ result = run_privileged([cls.certbot_bin(), 'certificates'], timeout=60)
# Parse certbot output (skip on a non-zero exit, but still surface the
# custom-installed certs below).
diff --git a/backend/app/utils/system.py b/backend/app/utils/system.py
index 023e44cf..691ff771 100644
--- a/backend/app/utils/system.py
+++ b/backend/app/utils/system.py
@@ -112,12 +112,15 @@ def is_command_available(cmd: str) -> bool:
"""Check whether *cmd* is available on the system.
Uses ``shutil.which`` first, then falls back to checking common sbin/local
- paths that may not be on the current ``$PATH``.
+ paths that may not be on the current ``$PATH``. ``/snap/bin`` is included
+ because snap is the recommended install method for tools like certbot, and
+ snap's bin dir is frequently missing from a service's ``$PATH``.
"""
if shutil.which(cmd):
return True
- for directory in ('/usr/bin', '/usr/sbin', '/usr/local/bin', '/usr/local/sbin'):
+ for directory in ('/usr/bin', '/usr/sbin', '/usr/local/bin',
+ '/usr/local/sbin', '/snap/bin'):
if os.path.exists(os.path.join(directory, cmd)):
return True
diff --git a/backend/tests/test_ssl_certbot_resolution.py b/backend/tests/test_ssl_certbot_resolution.py
new file mode 100644
index 00000000..56d8ec80
--- /dev/null
+++ b/backend/tests/test_ssl_certbot_resolution.py
@@ -0,0 +1,174 @@
+"""Tests for certbot binary resolution and the nginx-plugin preflight.
+
+Plan 73 item 1: certbot's recommended install is snap (/snap/bin/certbot),
+but the service used to hardcode /usr/bin/certbot, and issuance with
+``--nginx`` had no preflight for the nginx plugin — certbot's raw confusion
+was passed through to the panel. Pure unit tests: subprocess is mocked, no
+certbot/nginx needed.
+"""
+
+import subprocess
+from unittest.mock import patch
+
+import pytest
+
+from app.services import ssl_service
+from app.services.ssl_service import SSLService, resolve_certbot_bin
+
+
[email protected](autouse=True)
+def _clear_resolution_cache():
+ ssl_service.reset_certbot_resolution_cache()
+ yield
+ ssl_service.reset_certbot_resolution_cache()
+
+
+# ---------------------------------------------------------------------------
+# resolve_certbot_bin
+# ---------------------------------------------------------------------------
+class TestResolveCertbotBin:
+
+ def test_env_override_wins(self, monkeypatch):
+ monkeypatch.setenv('CERTBOT_BIN', '/opt/custom/certbot')
+ with patch('app.services.ssl_service.shutil.which',
+ return_value='/usr/bin/certbot'):
+ assert resolve_certbot_bin() == '/opt/custom/certbot'
+
+ def test_path_lookup_before_candidates(self, monkeypatch):
+ monkeypatch.delenv('CERTBOT_BIN', raising=False)
+ with patch('app.services.ssl_service.shutil.which',
+ return_value='/usr/local/bin/certbot'), \
+ patch('app.services.ssl_service.os.path.isfile', return_value=True):
+ assert resolve_certbot_bin() == '/usr/local/bin/certbot'
+
+ def test_snap_only_install_is_found(self, monkeypatch):
+ """certbot present only at /snap/bin/certbot (snap install) resolves."""
+ monkeypatch.delenv('CERTBOT_BIN', raising=False)
+ with patch('app.services.ssl_service.shutil.which', return_value=None), \
+ patch('app.services.ssl_service.os.path.isfile',
+ side_effect=lambda p: p == '/snap/bin/certbot'), \
+ patch('app.services.ssl_service.os.access', return_value=True):
+ assert resolve_certbot_bin() == '/snap/bin/certbot'
+
+ def test_usr_bin_candidate(self, monkeypatch):
+ monkeypatch.delenv('CERTBOT_BIN', raising=False)
+ with patch('app.services.ssl_service.shutil.which', return_value=None), \
+ patch('app.services.ssl_service.os.path.isfile',
+ side_effect=lambda p: p == '/usr/bin/certbot'), \
+ patch('app.services.ssl_service.os.access', return_value=True):
+ assert resolve_certbot_bin() == '/usr/bin/certbot'
+
+ def test_returns_none_when_missing(self, monkeypatch):
+ monkeypatch.delenv('CERTBOT_BIN', raising=False)
+ with patch('app.services.ssl_service.shutil.which', return_value=None), \
+ patch('app.services.ssl_service.os.path.isfile', return_value=False):
+ assert resolve_certbot_bin() is None
+
+ def test_result_is_cached(self, monkeypatch):
+ monkeypatch.setenv('CERTBOT_BIN', '/opt/custom/certbot')
+ with patch('app.services.ssl_service.shutil.which',
+ return_value='/usr/bin/certbot') as mock_which:
+ resolve_certbot_bin()
+ resolve_certbot_bin()
+ mock_which.assert_not_called()
+
+ def test_certbot_bin_falls_back_to_usr_bin(self, monkeypatch):
+ monkeypatch.delenv('CERTBOT_BIN', raising=False)
+ with patch('app.services.ssl_service.shutil.which', return_value=None), \
+ patch('app.services.ssl_service.os.path.isfile', return_value=False):
+ assert SSLService.certbot_bin() == SSLService.CERTBOT_FALLBACK
+
+
+# ---------------------------------------------------------------------------
+# nginx-plugin preflight in obtain_certificate
+# ---------------------------------------------------------------------------
+class TestNginxPluginPreflight:
+ """obtain_certificate(use_nginx=True) must fail with an actionable error
+ before ever invoking certbot for issuance when the nginx setup is broken."""
+
+ def _obtain(self, monkeypatch, plugins_stdout=None, plugins_rc=0,
+ nginx_available=True, certbot_path='/usr/bin/certbot',
+ issue_rc=1, issue_stderr='boom'):
+ """Drive obtain_certificate with fully mocked system interaction.
+
+ Returns (result, calls) where calls is every command passed to
+ run_privileged.
+ """
+ calls = []
+
+ def fake_run_privileged(cmd, **kwargs):
+ calls.append(cmd)
+ if 'plugins' in cmd:
+ return subprocess.CompletedProcess(
+ cmd, plugins_rc, stdout=plugins_stdout or '', stderr='')
+ return subprocess.CompletedProcess(
+ cmd, issue_rc, stdout='', stderr=issue_stderr)
+
+ monkeypatch.setattr(
+ SSLService, 'is_certbot_installed', classmethod(lambda cls: True))
+ with patch('app.services.ssl_service.run_privileged',
+ side_effect=fake_run_privileged), \
+ patch('app.services.ssl_service.is_command_available',
+ side_effect=lambda cmd: nginx_available), \
+ patch('app.services.ssl_service.resolve_certbot_bin',
+ return_value=certbot_path):
+ result = SSLService.obtain_certificate(
+ ['example.com'], '[email protected]')
+ return result, calls
+
+ def test_missing_nginx_plugin_gives_actionable_error(self, monkeypatch):
+ result, calls = self._obtain(
+ monkeypatch, plugins_stdout='* standalone\n* webroot\n')
+
+ assert result['success'] is False
+ assert 'python3-certbot-nginx' in result['error']
+ # certbot was probed for plugins but never invoked for issuance.
+ assert not any('certonly' in cmd for cmd in calls)
+ assert not any('--nginx' in cmd for cmd in calls)
+
+ def test_missing_nginx_binary_gives_actionable_error(self, monkeypatch):
+ result, calls = self._obtain(monkeypatch, nginx_available=False)
+
+ assert result['success'] is False
+ assert 'nginx binary not found' in result['error']
+ # Not even the plugins probe runs — certbot is never invoked.
+ assert calls == []
+
+ def test_preflight_ok_invokes_certbot_with_nginx(self, monkeypatch):
+ result, calls = self._obtain(
+ monkeypatch, plugins_stdout='* nginx\n* standalone\n',
+ certbot_path='/snap/bin/certbot',
+ issue_rc=1, issue_stderr='real certbot failure')
+
+ issuance = [cmd for cmd in calls if 'certonly' in cmd]
+ assert len(issuance) == 1
+ assert issuance[0][0] == '/snap/bin/certbot'
+ assert '--nginx' in issuance[0]
+ # Genuine issuance failures still pass certbot's stderr through raw.
+ assert result == {'success': False, 'error': 'real certbot failure'}
+
+ def test_plugin_probe_failure_falls_back_to_package_check(self, monkeypatch):
+ calls = []
+
+ def fake_run_privileged(cmd, **kwargs):
+ calls.append(cmd)
+ # `certbot plugins` itself fails -> fall back to dpkg/rpm check.
+ return subprocess.CompletedProcess(cmd, 1, stdout='', stderr='err')
+
+ monkeypatch.setattr(
+ SSLService, 'is_certbot_installed', classmethod(lambda cls: True))
+ with patch('app.services.ssl_service.run_privileged',
+ side_effect=fake_run_privileged), \
+ patch('app.services.ssl_service.is_command_available',
+ return_value=True), \
+ patch('app.services.ssl_service.resolve_certbot_bin',
+ return_value='/usr/bin/certbot'), \
+ patch('app.services.ssl_service.PackageManager.is_installed',
+ return_value=True):
+ result = SSLService.obtain_certificate(
+ ['example.com'], '[email protected]')
+
+ # Package check says the plugin is installed, so issuance proceeds
+ # (and fails with the passed-through stderr here).
+ assert any('certonly' in cmd for cmd in calls)
+ assert result == {'success': False, 'error': 'err'}