Differences

This shows you the differences between two versions of the page.

--- plugins:letsencrypt [2016/07/04 23:30]
nuxwin [Unknown Host Error]
+++ plugins:letsencrypt [2017/07/03 09:45]
nuxwin
@@ Line 1: / Line 1: @@
-======LetsEncrypt Plugin======
+<markdown>
+# i-MSCP LetsEncrypt plugin
+</markdown>
+<WRAP center round important 60%>
+**Bear in mind that this documentation is for the last available version. If you use an older version, you must refer to the README.md file inside the plugin archive.**
+</WRAP>
+<markdown>
+## Introduction
-This plugin allows to activate Let's Encrypt for selected domains.
+Provides free SSL certificates through the Let's Encrypt CA.
-=====Requirements=====
+## Requirements
-  * i-MSCP Serie 1.3.x
+- i-MSCP Serie ≥ 1.4.x
-=====Installation=====
+## Installation
-  - Download the **LetsEncrypt** plugin archive from the [[http://i-mscp.net/filebase/index.php/File/33-LetsEncrypt/|plugin store]]
+. Be sure that all requirements as stated in the requirements section are met
-  - Login into the panel as admin and go to the plugin management interface
+. Upload the plugin through the plugin management interface
-  - Upload the **LetsEncrypt** plugin archive
+. Edit the plugin configuration file according your needs
-  - Click on the **Update Plugins** button
+. Install the plugin through the plugin management interface
-  - Activate the plugin
-=====Update=====
+Note that the plugin installation can take up several minutes.
-  - Backup your current config file **plugins/LetsEncrypt/config.php**
+## Update
-  - Download the **LetsEncrypt** plugin archive from the [[http://i-mscp.net/filebase/index.php/File/33-LetsEncrypt/|plugin store]]
-  - Login into the panel as admin and go to the plugin management interface
-  - Upload the **LetsEncrypt** plugin archive
-  - Restore your **plugins/LetsEncrypt/config.php** ( compare it with new version first )
-  - Click on the **Update Plugins** button in the plugin management interface
-=====Troubleshooting=====
+. Be sure that all requirements as stated in the requirements section are met
+. Backup your plugin configuration file if needed
+. Upload the plugin through the plugin management interface
-====Unknown Host Error====
+Note that the plugin update can take up several minutes.
-  Failed authorization procedure. www.domain.tld (http-01): urn:acme:error:unknownHost :: The server could not resolve a domain name :: No valid IP addresses found for www.domain.tld
+### Restore you plugin configuration file if needed
-If you get such error, be sure to add a **www** CNAME DNS resource record for each of your domains
+. Restore your plugin configuration file (compare it with the new version first)
+. Update the plugin list through the plugin management interface
-=====Sponsors=====
+## Plugin deactivation/uninstallation
-  - [[https://www.ip-projects.de/|IP-Projects GmbH & Co. KG]]
+When deactivating or uninstalling the plugin, the existents SSL certificate
+lineages are not removed. Also, the database entries that belong to customer
+SSL certificates are keep in place. This means that any SSL certificate
+already issued will still be usable by the customer.
-=====Author=====
+According to the previous sentence, It must be noted that the current actions
+for SSL certificates that are displayed in the interface, at customer and
+administrator levels, do not predict the action that will actually take place.
-  * Ninos Ego <me@ninosego.de>
+The real action to be performed will be automagically determined by the plugin
+at run time, by checking the state of the SSL certificate. In other words, the
+plugin is smart enough to not perform new SSL certificate issuance or renewal
+when that is not necessary.
-=====Contributor=====
+## Manual execution of the Certbot client
-  * Laurent Declercq <[email protected]>
+You should avoid execute the `Certbot` client manually, or even through your
+own scripts, without knowing what your are doing. If you really want execute
+the `Certbot` client manually, you should at least reuse the email that is used
+by this plugin. You can find the email address in the `/etc/imscp/imscp.conf`
+file (DEFAULT_ADMIN_ADDRESS parameter).
+Be aware that not support will be given if following a manual invocation of the
+Certbot client, one or many of your SSL certificate lineages are in
+inconsistent states.
+## Certbot client version
+It is possible to use latest released version or development version of the
+Certbot client by changing the value of the `certbot_version` configuration
+parameter in the plugin configuration file. Be aware that usage of the
+development version is discouraged in production environments.
+## Let's Encrypt registration
+The plugin automatically process your Let's Encrypt account registration, using
+the administrator email address that you have provided during i-MSCP setup
+phase. If you need change that email after while, you must not forget to run
+the following command to update your Let's Encrypt account:
+```
+certbot register --update-registration --email <new_email>
+```
+where `<new_email>` is your new email address.
+If you don't do so, a new account will be created using the new email address
+and there will be inconsistencies with SSL certificate lineages, making the
+plugin unable to work properly.
+## Let's Encrypt Rate Limits
+Be sure to read https://letsencrypt.org/docs/rate-limits
+Note that when the Let's Encrypt limits are reached, the plugin will
+automatically set the status of the SSL certificate to `pending`.
+The pending tasks are postponed as long as the limits are not released.
+## Let's Encrypt SSL certificates for the control panel and services (FTP, IMAP/POP and SMTP)
+To enable Let's Encrypt for the control panel and/or services you must in
+order:
+- Enable SSL on i-MSCP side for the control panel and/or services, by choosing
+  the `self-signed` SSL certificate option
+- Connect as administrator to the control panel
+- Activate Let's Encrypt for the control panel and/or services through the
+  administrator's Let's Encrypt interface.
+The link for accessing the administrator's Let's Encrypt interface is available
+in the `System tools` section.
+### Note for PanelRedirect plugin users
+If you use the `PanelRedirect` plugin, you must ensure that you have a version
+greater or equal to `1.1.5`, else, the domain validations will fail.
+## SANs for alternative URLs
+You can enable support for alternative URLs by setting the `include_altnames`
+configuration parameter to `true` in the plugin configuration file. Once done,
+don't forget to trigger a plugin list update.
+Be aware that this parameters acts only for new SSL certificate issuances.
+### Warning regarding this feature
+Due to the current Let's Encrypt rate limits, it is not recommended to enable
+this feature. Indeed, each SSL certificate issuance for which a SAN is added
+for an alternative URL will possibly hits the `Certificate per Registered
+Domain` limit (20 per week) for the control panel domain. This explain why this
+feature is turned off by default.
+Note that alternative URLs as provided by i-MSCP are meant to allow the
+customers to access their domains for DNS propagation time. These URLs should
+not be exposed publicly.
+## Plugin translation
+You can translate this plugin using a gettext translation editor such as
+`Poedit`. Translation files are located under the `./l10n` directory, inside of
+the plugin archive. Once translated you can send us your translation file (po
+file) for integration in future release.
+Note that if no translation file exists for your localization in the
+`./l10n/po` directory, you must create it first from the `l10n/LetsEncrypt.pot`
+file. Be aware that your file must be `UTF-8`, else, it won't be accepted.
+## License
+    i-MSCP LetsEncrypt plugin
+    @author Laurent Declercq <[email protected]>
+    @copyright (C) 2016-2017 Laurent Declercq <[email protected]>
+    @license i-MSCP License <https://www.i-mscp.net/license-agreement.html>
+See the LICENSE file inside the archive for further details.
+## Sponsors
+The development of this plugin has been sponsored by:
+ - [IP-Projects GmbH & Co. KG](https://www.ip-projects.de/ "IP-Projects GmbH & Co. KG")
+</markdown>

i-MSCP Documentation

User Tools

Site Tools

Differences

Page Tools