Certbot 開發人員指南

入門

設置用于開發時，Certbot具有相同的系統要求。盡管以下部分將幫助您安裝Certbot及其依賴項，但Certbot需要在類似UNIX的操作系統上運行，因此，如果您使用Windows，則需要設置運行Linux等操作系統的（虛擬）計算機并在類似UNIX的操作系統上繼續執行這些說明。

運行客戶端的本地副本

從本地樹以開發人員模式運行客戶端與以用戶身份運行Certbot有點不同。要進行設置，請通過運行以下命令克隆我們的git存儲庫：

git clone https://github.com/certbot/certbot

如果您使用的是macOS，建議您跳過本節的其余部分，而應在Docker中運行Certbot。您可以在此處找到有關操作方法的說明。如果您在Linux上運行，則可以運行以下命令來安裝依賴項并設置可以在其中運行Certbot的虛擬環境。

安裝運行Certbot所需的OS系統依賴項。

# For APT-based distributions (e.g. Debian, Ubuntu ...)
sudo apt update
sudo apt install python3-dev python3-venv gcc libaugeas0 libssl-dev
                 libffi-dev ca-certificates openssl
# For RPM-based distributions (e.g. Fedora, CentOS ...)
# NB1: old distributions will use yum instead of dnf
# NB2: RHEL-based distributions use python3X-devel instead of python3-devel (e.g. python36-devel)
sudo dnf install python3-devel gcc augeas-libs openssl-devel libffi-devel
                 redhat-rpm-config ca-certificates openssl

設置將托管您的Certbot本地實例的Python虛擬環境。

cd certbot
python tools/venv3.py

注意
當Certbot的依賴項更改或引入新插件時，您可能需要重復此操作。

現在，您可以通過執行venv3/bin/certbot或激活虛擬環境來從git運行Certbot的副本。您可以通過運行以下命令來完成后者：

source venv3/bin/activate

運行此命令后，certbot和開發工具，如ipdb， ipython，pytest，和tox是在運行命令shell中可用。這些工具安裝在虛擬環境中，并且與全局Python安裝分開。這可以通過設置環境變量來工作，以便找到正確的可執行文件，并且Python可以提取Certbot所需的各種軟件包的版本。

找到需要解決的問題

您可以在github問題跟蹤器中找到未解決的問題。

分支正常工作后，您可以打開拉取請求。您的拉取請求中的所有更改都必須具有全面的單元測試范圍，通過我們的測試并符合編碼風格。

測試

您可以通過多種方式測試代碼：

運行自動化的單元測試，
運行自動化集成測試
運行臨時手動集成測試

運行自動化的單元測試

當您使用文件時foo.py，還應該在與子目錄foo_test.py 相同的目錄中foo.py或在tests子目錄中有一個文件（如果沒有，則創建一個）。在處理代碼和測試時，請運行python foo_test.py 以運行相關的測試。

為了進行調試，建議將 import ipdb; ipdb.set_trace()語句放在源代碼中。

完成代碼更改并通過測試之后foo_test.py ，請運行Certbot的所有單元測試，并使用tox -e py3-cover來檢查覆蓋范圍。然后，您應該使用tox -e lint（所有文件）或pylint --rcfile=.pylintrc path/to/file.py（一次單個文件）檢查代碼樣式。

上述所有方法均成功完成后，您可以使用tox --skip-missing-interpreters來運行完整的測試套件。我們建議您首先運行上面的命令，因為運行所有這樣的測試非常慢，并且大量的輸出會使得在發生特定故障時很難發現它們。

警告
如果您的用戶具有sudo權限，則完整的測試套件可能會嘗試修改系統的Ap??ache配置，因此不應在生產的Apache服務器上運行它。

運行自動化集成測試

通常，打開一個請求請求并讓Github和Travis為您運行集成測試就足夠了。但是，您可能要在提交請求之前在本地運行它們。您需要安裝并運行Docker和docker-compose。

Tox環境integration將設置Pebble讓我們加密ACME CA服務器）進行集成測試，然后啟動Certbot集成測試。

允許用戶訪問您本地的Docker守護程序，運行：

tox -e integration

測試將使用pytest運行。在集成測試執行結束時，將顯示一個測試報告和一個代碼覆蓋率報告。

運行手動集成測試

您還可以針對Pebble ACME服務器的本地實例手動執行Certbot 。這對于驗證對代碼所做的修改是否使Certbot表現出預期的效果很有用。

為此，您需要：

已安裝Docker，并且有權訪問Docker客戶端的用戶，
Certbot 的可用本地副本。

使用設置的虛擬環境包含兩個命令，一旦激活虛擬環境，便可以使用它們：python tools/venv3.py

run_acme_server

啟動Pebble的本地實例并在前臺運行以打印其日志。
按CTRL + C停止此實例。
該實例配置為驗證針對本地執行的certbot的質詢。

certbot_test [ARGS…]

使用提供的參數和可用于測試目的的其他參數執行certbot，例如：詳細輸出，萬一Certbot崩潰時的完整回溯等。
執行已預先配置為與以開頭的Pebble CA進行交互run_acme_server。
可以將任何參數傳遞給Certbot（例如）。certbot_test certonly -d test.example.com

這是驗證Certbot在具有Python 3的計算機上使用HTTP-01挑戰成功頒發證書的典型工作流程：

python tools/venv3.py
source venv3/bin/activate
run_acme_server &
certbot_test certonly --standalone -d test.example.com
# To stop Pebble, launch `fg` to get back the background job, then press CTRL+C

在CI中運行測試

Certbot使用Azure Pipelines和Travis來運行連續集成測試。如果您使用我們的Azure和Travis設置，則名稱以開頭的分支test-將在該分支上運行所有Azure和Travis測試。如果分支名稱以開頭azure-test-，它將運行我們所有的Azure測試，而不運行我們的Travis測試。如果分支以開頭travis-test-，則只會運行我們的Travis測試。

代碼組件和布局

Certbot存儲庫的以下組件已分發給用戶：

acme

包含所有協議特定的代碼

certbot

主要客戶代碼

certbot-apache和certbot-nginx

客戶端代碼以配置特定的Web服務器

certbot-dns- *

客戶端代碼以配置DNS提供程序

certbot-auto and letsencrypt-auto

在UNIX系統上安裝Certbot及其依賴項的Shell腳本

windows installer

在Windows上安裝Certbot，并使用Windows-installer /中的文件構建

插件架構

Certbot具有插件架構，以促進對不同的Web服務器，其他TLS服務器和操作系統的支持。可用于插件實現的接口在interfaces.py和plugins / common.py中定義。

主要的兩個插件接口是IAuthenticator，用于實現向證書頒發機構證明域控制的各種方法，以及IInstaller，用于配置服務器以在證書頒發后使用證書。某些插件（例如內置的Apache和Nginx插件）實現了這兩個接口并執行了這兩項任務。其他一些，例如內置的Standalone驗證器，僅實現一個接口。

還有一些IDisplay插件，可以更改向用戶顯示提示的方式。

認證者

身份驗證器是通過解決ACME服務器提供的挑戰來證明對域名的控制的插件。ACME當前定義了幾種類型的挑戰：HTTP，TLS-ALPN和DNS，由中的類表示acme.challenges。身份驗證器插件應實現對至少一種挑戰類型的支持。

身份驗證器通過實施get_chall_pref(domain)以優先順序返回挑戰類型的排序列表來指示其支持的挑戰。

身份驗證器還必須實現perform(achalls)，它例如通過在HTTP服務器上配置文件或在DNS中設置TXT記錄來“執行”挑戰列表。一旦所有挑戰成功或失敗，Certbot都會調用該插件的cleanup(achalls)方法來刪除僅在身份驗證期間需要的任何文件或DNS記錄。

安裝程序

存在安裝程序插件可在服務器中實際設置證書，可能會調整安全性配置以使其更正確和安全（解決一些混合內容問題，打開HSTS，重定向到HTTPS等）。安裝程序插件通過supported_enhancements()呼叫告知主要客戶他們完成后者的能力。當前，我們在樹中有兩個Installers ApacheConfigurator。和 NginxConfigurator。外部項目在支持IIS，Icecast和Plesk方面取得了一些進展。

安裝程序和身份驗證器通常是相同的類/對象（例如，這兩個任務都可以由像nginx這樣的網絡服務器執行），盡管并非總是如此（獨立插件是偵聽端口80的身份驗證器，但無法安裝）證書；后綴插件將是安裝程序，而不是身份驗證器）。

安裝程序和身份驗證器是分開的，因為應該可以將StandaloneAuthenticator它（自己設置自己的Python服務器來執行挑戰）與本身無法解決挑戰的程序一起使用（例如MTA安裝程序）。

安裝程式開發

有一些現有的課程在開發新課程時可能是有益的IInstaller。旨在重新配置UNIX服務器的安裝程序可以使用Augeas進行配置解析，并且可以從AugeasConfigurator類繼承來處理許多接口。無法使用Augeas的安裝程序可能仍會發現Reverter該類在處理配置檢查點和回滾方面很有幫助。

編寫自己的插件

注意
Certbot團隊目前不接受任何新的DNS插件，因為我們想重新思考應對挑戰的方法，并首先解決＃6464，＃6503和＃6504之類的問題。

Certbot客戶端支持通過使用組的setuptools入口點動態發現插件certbot.plugins。這樣，您可以例如創建IAuthenticator或的自定義實現， IInstaller而不必將其與核心上游源代碼合并。examples/plugins/目錄中提供了一個示例。

在開發過程中，您可以將插件安裝到Certbot開發virtualenv中，如下所示：

. venv/bin/activate
pip install -e examples/plugins/
certbot_test plugins

您的插件應顯示在最后一條命令的輸出中。如果不是，則未正確安裝。

插件完成并發布后，您可以讓用戶在系統范圍內安裝。請注意，這僅適用于通過OS軟件包或通過pip安裝了Certbot的用戶。運行用戶當前無法使用第三方插件。從技術上講，可以將第三方插件安裝到所使用的virtualenv中，但是在升級時，它們會消失。pip install``certbot-auto``certbot-auto``certbot-auto

編碼風格

請：

與其余代碼保持一致。
閱讀PEP 8-Python樣式指南。

請遵循Google Python樣式指南，但我們使用Sphinx樣式的文檔除外：

def foo(arg):
    """Short description.

 :param int arg: Some number.

 :returns: Argument
 :rtype: int

 """
    return arg

記住要使用pylint。

使用`certbot.compat.os`代替`os`

Python的標準庫os模塊缺少對文件權限（例如DACL）的Windows安全功能的全面支持。但是，由Certbot處理的多個文件（例如私鑰）在Linux和Windows上都需要嚴格限制訪問。

為了解決這個問題，該certbot.compat.os模塊包裝了標準 os模塊，并禁止使用缺少對這些Windows安全功能的支持的方法。

作為開發人員，在使用Certbot或其插件時，必須certbot.compat.os 在所需的每個位置使用os（例如from certbot.compat import os而不是 import os）。否則，提交您的PR時測試將失敗。

Mypy類型注釋

Certbot使用mypy靜態類型檢查器。Python 3本機支持正式的類型注釋，然后可以使用mypy對其進行一致性測試。Python 2沒有，但是可以在comments中添加類型注釋。Mypy即使沒有類型注釋也可以進行一些類型檢查。即使沒有完全注釋的代碼庫，我們也可以在Certbot中找到錯誤。

Certbot同時支持Python 2和3，因此我們使用的是Python 2樣式的注釋。

Zulip撰寫了使用mypy 的出色指南。這很有用，但是您不必閱讀全部內容即可開始為Certbot做出貢獻。

要在Certbot上運行mypy，請在已安裝Python 3的計算機上使用tox -e mypy。

請注意typing，由于包裝方面的問題，我們不僅從import導入，acme.magic_typing而且在Certbot中從中導入，并且必須為pylint添加一些注釋，如下所示：

from acme.magic_typing import Dict

還要注意，我們所依賴的OpenSSL具有加密類型定義，但沒有SSL類型。我們都使用。這些導入應如下所示：

from OpenSSL import crypto
from OpenSSL import SSL # type: ignore # https://github.com/python/typeshed/issues/2052

提交拉取請求

Steps:

編寫您的代碼！執行此操作時，應為添加或修改的任何功能添加mypy類型注釋。您可以通過在安裝了Python 3的計算機上運行tox -e mypy來檢查是否已正確完成此操作。
確保您的環境設置正確并且位于虛擬環境中。您可以按照“ 入門”部分中的說明進行操作。
運行tox -e lint以檢查pylint錯誤。修復所有錯誤。
運行以運行包括覆蓋率在內的整個測試套件。該參數忽略運行測試所需的缺少的Python版本。修復所有錯誤。tox --skip-missing-interpreters``--skip-missing-interpreters
提交PR。PR打開后，請勿強行推入包含拉取請求的分支以壓榨或修改提交。我們在PR上使用壓縮合并，并且重寫提交使更改很難在兩次評論之間進行跟蹤。
您的測試通過了Travis嗎？如果沒有，請更正所有錯誤。

尋求幫助

如果您在處理Certbot問題時有任何疑問，請隨時尋求幫助！您可以在EFF的Mattermost實例的Certbot通道中針對其開源項目執行此操作，如下所述。

您可以參與EFF的多個軟件項目，例如EFF開源貢獻者聊天平臺上的 Certbot 。注冊EFF開源貢獻者聊天平臺，即表示您同意與該平臺的運營商和數據控制者電子前沿基金會共享您的個人信息。EFF和EFFOSCCP的其他用戶都可以使用該頻道，他們可以在EFFOSCCP之外的這些頻道中使用或公開信息。根據隱私政策，EFF將使用您的信息來促進EFF的使命，包括主持和主持該平臺上的討論。

EFFOSCCP的使用受EFF行為準則的約束。當調查涉嫌違反《行為準則》的行為時，EFF可能會審查討論渠道或直接消息。

更新certbot-auto和letencrypt-auto

注意
目前，我們僅接受對certbot-auto的更改，該更改可修復在https://certbot.eff.org/instructions 上推薦的certbot-auto是推薦的安裝方法的平臺上的回歸。

更新腳本

開發人員應該不能修改certbot-auto和letsencrypt-auto文件在存儲庫的根目錄。而是分別修改和目錄letsencrypt-auto.template中的letsencrypt-auto-source和特定于平臺的Shell腳本letsencrypt-auto-source/pieces/bootstrappers。

構建letencrypt-auto-source / letsencrypt-auto

一旦更改了上述任何文件，就 letsencrypt-auto-source/letsencrypt-auto應更新腳本。代替手動更新此腳本，請運行構建腳本，該腳本位于 letsencrypt-auto-source/build.py：

python letsencrypt-auto-source/build.py

運行build.py將更新letsencrypt-auto-source/letsencrypt-auto 腳本。請注意，運行此腳本后，存儲庫根目錄中的certbot-auto和letsencrypt-auto腳本將保持不變。您的更改將在下一版Certbot中傳播到這些文件。

打開PR

打開PR時，請確保已提交以下文件：

letsencrypt-auto-source/letsencrypt-auto.template 和 letsencrypt-auto-source/pieces/bootstrappers/*
letsencrypt-auto-source/letsencrypt-auto（由生成build.py）

仔細檢查沒有對存儲庫根目錄中的certbot-auto或letsencrypt-auto腳本進行任何更改，這些腳本將在下一個版本中由核心開發人員更新。

更新文檔

Certbot存儲庫中的許多軟件包在docs/目錄中都有文檔。該目錄位于軟件包的頂級目錄下。例如，Certbot的文檔在下 certbot/docs。

要生成軟件包的文檔，請確保已按照說明進行操作，以設置Certbot 的本地副本，包括激活虛擬環境。之后，cd您要構建到docs目錄并運行以下命令：

make clean html

這將_build/html在當前 docs/目錄中生成HTML文檔。

使用Docker運行客戶端

您可以使用Docker Compose快速設置運行和測試Certbot的環境。要安裝Docker Compose，請按照https://docs.docker.com/compose/install/ 上的說明進行操作。

注意
Linux用戶可以按照入門部分pip install docker-compose中所述，在安裝Docker Engine并激活您的Shell之后，簡單地運行以獲取Docker Compose 。

現在，您可以在主機上進行開發，但是可以運行Certbot并在Docker中測試您的更改。使用時，請docker-compose確保您位于Certbot存儲庫的克隆中。例如，您可以運行以下命令來檢查錯誤：

docker-compose run --rm --service-ports development bash -c 'tox -e lint'

您還可以在Docker容器中運行外殼的終端保持打開狀態，并在另一個窗口中修改Certbot代碼。主機上的Certbot存儲庫安裝在容器內，因此您所做的任何更改都會立即生效。為此，請運行：

docker-compose run --rm --service-ports development bash

現在運行上述檢查棉絨錯誤的操作非常簡單：

tox -e lint

有關操作系統依賴性的說明

操作系統級別的依賴項可以這樣安裝：

./certbot-auto --debug --os-packages-only

一般來說…

sudo 是運行特權進程的建議方法
需要Python2.7或3.5+
Python綁定需要Augeas
virtualenv 用于管理其他Python庫依賴項

FreeBSD

FreeBSD默認使用tcsh。為了激活virtualenv，您將需要兼容的shell，例如。pkg install bash && bash

本文章首發在網安wangan.com 網站上。