User Tools

Site Tools


plugins:letsencrypt

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Last revision Both sides next revision
plugins:letsencrypt [2016/11/23 16:29]
nuxwin [Note for PanelRedirect plugin users]
plugins:letsencrypt [2017/09/13 23:37]
nuxwin
Line 1: Line 1:
-====== LetsEncrypt Plugin ====== 
- 
 <WRAP center round important 60%> <WRAP center round important 60%>
-**Be aware that this documentation is always referring ​to the latest LetsEncrypt ​plugin ​version.**+**Bear in mind that this documentation is for the last released version. If you use an older version, you must refer to the README.md file inside the plugin ​archive.**
 </​WRAP>​ </​WRAP>​
  
-===== Introduction ===== +<​markdown>​ 
-This plugin ​provides free SSL certificates through the Let's Encrypt CA.+# i-MSCP LetsEncrypt ​plugin
  
-===== Requirements =====+## Introduction
  
-  * i-MSCP Serie 1.3.x (version >= 1.3.1 - Plugin API 1.0.5)+Provides free SSL certificates through the Let's Encrypt CA.
  
-==== Debian / Ubuntu packages ====+## Requirements
  
-  * libarray-diff-perl +i-MSCP Serie ≥ 1.4.x
-  * libconvert-asn1-perl +
-  * libdatetime-format-strptime-perl+
  
-You can install these packages by executing the following commands:+## Installation
  
-    # apt-get update +1. Be sure that all requirements as stated in the requirements section are met 
-    # apt-get install -y libarray-diff-perl libconvert-asn1-perl libdatetime-format-strptime-perl+2. Upload the plugin through the plugin management interface 
 +3. Edit the plugin configuration file according your needs 
 +4. Install the plugin through the plugin management interface
  
-===== Installation ===== +Note that the plugin ​installation can take up several minutes.
-  - Be sure that all requirements as stated in the requirements section are met +
-  - Upload the plugin through the plugin management interface +
-  - Install the plugin through ​the plugin ​management interface+
  
-Note that depending on your network connection and processor capacity, the installation can take up several minutes.+## Update
  
-===== Update =====+1. Be sure that all requirements as stated in the requirements section are met 
 +2. Backup your plugin configuration file if needed 
 +3. Upload the plugin through the plugin management interface
  
-  - Be sure to read the update ​notes in the UPDATE.md file +Note that the plugin ​update ​can take up several minutes.
-  - Be sure that all requirements as stated in the requirements section are met +
-  - Upload the plugin through the plugin management interface +
-  - Update the plugin list through the plugin management interface+
  
-===== Plugin deactivation/​uninstallation =====+### Restore you plugin configuration file if needed
  
-When deactivating,​ or when uninstalling the pluginthe existents SSL certificate lineages are not removedAlso 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, even if the plugin ​has been deactivated or uninstalled.+1. Restore your plugin ​configuration file (compare it with the new version first) 
 +2Update ​the plugin list through ​the plugin ​management interface
  
-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. The real action to be performed will be automagically determined by the plugin at run time (backend side), 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.+## Plugin deactivation/​uninstallation
  
-===== Manual execution of the certbot client =====+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.
  
-You should avoid execute ​the Certbot client manuallyor even through your own scripts, without knowing what your are doing. If you really want execute ​the `Certbot` client manuallyyou 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).+According to the previous sentenceIt 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.
  
-Be aware that not support ​will be given if following a manual invocation of the Certbot clientone or many of your SSL lineages are in inconsistent states.+The real action to be performed ​will be automagically determined by the plugin 
 +at run timeby 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.
  
-===== Certbot client ​version =====+## Manual execution of the Certbot client
  
-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 fileBe aware that usage of the development version is discouraged ​in production environments.+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 `Certbotclient ​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).
  
-===== Let's Encrypt registration =====+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.
  
-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, you must not forget to run the following command to update your Let's Encrypt account:+## Certbot client version
  
-    # certbot-auto register --update-registration --email <​new_email>​+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.
  
-where **<​new_email>​** is your new email address.+## Let's Encrypt registration
  
-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 lineagesmaking ​the plugin unable ​to work properly.+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 whileyou must not forget to run 
 +the following command ​to update your Let's Encrypt account:
  
-===== Let's Encrypt Rate Limits =====+``` 
 +certbot register --update-registration --email <​new_email>​ 
 +```
  
-Be sure to read https://​letsencrypt.org/​docs/​rate-limits+where `<​new_email>​` is your new email address.
  
-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.+If you don't do soa 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 ​SSL certificates for the control panel and services (FTP, IMAP/POP and SMTP) =====+## Let's Encrypt ​Rate Limits
  
-To enable Let's Encrypt for the control panel and/or services you must in order:+Be sure to read https://​letsencrypt.org/​docs/​rate-limits
  
-  - Enable SSL on i-MSCP side for the control panel and/or servicesby choosing ​the `self-signedSSL certificate option +Note that when the Let's Encrypt limits are reached, the plugin will 
-  - Connect ​as administrator to the control panel +automatically set the status of the SSL certificate to `pending`. 
-  - Activate Let's Encrypt for the control panel and/or services through the administrator'​s Let's Encrypt interface.+The pending tasks are postponed as long as the limits are not released.
  
-The link for accessing the administrator'​s ​Let's Encrypt ​interface is available in the system tools page.+## Let's Encrypt ​SSL certificates for the control panel and services (FTP, IMAP/POP and SMTP)
  
-Note that it is important to not disable this plugin when updating or reconfiguring i-MSCP because there is an event listener that replace the default SSL certificates by the Let's Encrypt ​SSL certificates. If the LetsEncrypt plugin is disabled, the event listener won't be registered ​and so, the SSL certificates won't be replaced.+To enable ​Let's Encrypt ​for the control panel and/or services you must in 
 +order:
  
-Be aware that this feature is still experimental.+- 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.
  
-==== Regarding SSL certificate ​for the control panel ====+The link for accessing ​the administrator'​s Let's Encrypt interface is available 
 +in the `System tools` section.
  
-Note that after enabling Let's Encrypt ​for the control panel, you may have to close and re-open your browser. Indeed, in some cases, the newly created SSL certificate is not loaded after a simple page refresh.+### Note for PanelRedirect plugin users
  
-===== Note for PanelRedirect plugin ​users =====+If you use the `PanelRedirectplugin, you must ensure that you have a version 
 +greater or equal to `1.1.5`, else, the domain validations will fail.
  
-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
  
-===== 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, 
-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.+don't forget to trigger a plugin list update.
  
 Be aware that this parameters acts only for new SSL certificate issuances. Be aware that this parameters acts only for new SSL certificate issuances.
  
-==== Warning regarding this feature ​====+### 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 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.+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.+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 ​=====+## 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 this plugin archive. Once translated you can send us your translation file (po file) for integration in future release.+You can translate this plugin using a gettext translation editor such as 
 +`Poedit`. Translation files are located under the `./l10ndirectory, 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.+Note that if no translation file exists for your localization in the 
 +`./l10n/podirectory, 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 ​=====+## License
  
     i-MSCP LetsEncrypt plugin     i-MSCP LetsEncrypt plugin
-    ​+
     @author Laurent Declercq <​[email protected]>​     @author Laurent Declercq <​[email protected]>​
-    ​@author Ninos Ego <​[email protected]>​ +    @copyright (C) 2016-2017 Laurent Declercq <​[email protected]>​
-    ​@copyright (C) 2016 Laurent Declercq <​[email protected]+
-    @copyright (C) 2016 Ninos Ego <​[email protected]>+
     @license i-MSCP License <​https://​www.i-mscp.net/​license-agreement.html>​     @license i-MSCP License <​https://​www.i-mscp.net/​license-agreement.html>​
  
 See the LICENSE file inside the archive for further details. See the LICENSE file inside the archive for further details.
  
-===== Sponsors ​=====+## Sponsors
  
 The development of this plugin has been sponsored by: The development of this plugin has been sponsored by:
  
-[IP-Projects GmbH & Co. KG](https://​www.ip-projects.de/​ "​IP-Projects GmbH & Co. KG") + ​- ​[IP-Projects GmbH & Co. KG](https://​www.ip-projects.de/​ "​IP-Projects GmbH & Co. KG")
- +
-===== Authors =====+
  
-  * Laurent Declercq ​<[email protected]>​ +</markdown>
-  * Ninos Ego <​[email protected]>+
/var/www/virtual/i-mscp.net/wiki/htdocs/data/pages/plugins/letsencrypt.txt · Last modified: 2017/09/13 23:39 by nuxwin