This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Last revision Both sides next revision | ||
plugins:letsencrypt [2017/02/28 19:49] nuxwin |
plugins:letsencrypt [2017/09/13 23:37] nuxwin |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | <markdown> | ||
- | # i-MSCP LetsEncrypt plugin | ||
- | </markdown> | ||
<WRAP center round important 60%> | <WRAP center round important 60%> | ||
- | **Be aware 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.** | + | **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> | ||
+ | |||
<markdown> | <markdown> | ||
+ | # i-MSCP LetsEncrypt plugin | ||
+ | |||
## Introduction | ## Introduction | ||
Line 12: | Line 12: | ||
## Requirements | ## Requirements | ||
- | * i-MSCP Serie 1.3.x (version >= 1.3.1 - Plugin API 1.0.5) | + | - i-MSCP Serie ≥ 1.4.x |
- | + | ||
- | ### Debian / Ubuntu packages | + | |
- | + | ||
- | - ca-certificates | + | |
- | - git | + | |
- | - libarray-diff-perl | + | |
- | - libconvert-asn1-perl | + | |
- | - libdatetime-format-strptime-perl | + | |
- | + | ||
- | You can install these packages by executing the following commands: | + | |
- | + | ||
- | # apt-get update | + | |
- | # apt-get install -y ca-certificates git libarray-diff-perl libconvert-asn1-perl libdatetime-format-strptime-perl | + | |
## Installation | ## Installation | ||
Line 31: | Line 18: | ||
1. Be sure that all requirements as stated in the requirements section are met | 1. Be sure that all requirements as stated in the requirements section are met | ||
2. Upload the plugin through the plugin management interface | 2. Upload the plugin through the plugin management interface | ||
- | 3. Install 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 | ||
- | Note that the installation can take up several minutes. | + | Note that the plugin installation can take up several minutes. |
## Update | ## Update | ||
- | 1. Be sure to read the update notes in the UPDATE.md file | + | 1. Be sure that all requirements as stated in the requirements section are met |
- | 2. 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 | 3. Upload the plugin through the plugin management interface | ||
- | 4. Update the plugin list through the plugin management interface | + | |
+ | Note that the plugin update can take up several minutes. | ||
+ | |||
+ | ### Restore you plugin configuration file if needed | ||
+ | |||
+ | 1. Restore your plugin configuration file (compare it with the new version first) | ||
+ | 2. Update the plugin list through the plugin management interface | ||
## Plugin deactivation/uninstallation | ## Plugin deactivation/uninstallation | ||
- | When deactivating or uninstalling the plugin, the existents SSL certificate lineages are not removed. Also, the database | + | When deactivating or uninstalling the plugin, the existents SSL certificate |
- | entries that belong to customer SSL certificates are keep in place. This means that any SSL certificate already issued | + | lineages are not removed. Also, the database entries that belong to customer |
- | will still be usable by the customer. | + | SSL certificates are keep in place. This means that any SSL certificate |
+ | already issued will still be usable by the customer. | ||
+ | |||
+ | 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. | ||
- | According to the previous sentence, It must be noted that the current actions for SSL certificates that are displayed in | + | The real action to be performed will be automagically determined by the plugin |
- | the interface, at customer and administrator levels, do not predict the action that will actually take place. The real | + | at run time, by checking the state of the SSL certificate. In other words, the |
- | action to be performed will be automagically determined by the plugin at run time, by checking the state of the SSL | + | plugin is smart enough to not perform new SSL certificate issuance or renewal |
- | certificate. In other words, the plugin is smart enough to not perform new SSL certificate issuance or renewal when that | + | when that is not necessary. |
- | is not necessary. | + | |
## Manual execution of the Certbot client | ## Manual execution of the Certbot client | ||
- | You should avoid execute the `Certbot` client manually, or even through your own scripts, without knowing what your are | + | You should avoid execute the `Certbot` client manually, or even through your |
- | doing. If you really want execute the `Certbot` client manually, you should at least reuse the email that is used by | + | own scripts, without knowing what your are doing. If you really want execute |
- | this plugin. You can find the email address in the `/etc/imscp/imscp.conf` file (DEFAULT_ADMIN_ADDRESS parameter). | + | 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 | + | Be aware that not support will be given if following a manual invocation of the |
- | certificate lineages are in inconsistent states. | + | Certbot client, one or many of your SSL certificate lineages are in |
+ | inconsistent states. | ||
## Certbot client version | ## Certbot client version | ||
- | It is possible to use latest released version or development version of the Certbot client by changing the value of the | + | It is possible to use latest released version or development version of the |
- | `certbot_version` configuration parameter in the plugin configuration file. Be aware that usage of the development | + | Certbot client by changing the value of the `certbot_version` configuration |
- | version is discouraged in production environments. | + | parameter in the plugin configuration file. Be aware that usage of the |
+ | development version is discouraged in production environments. | ||
## Let's Encrypt registration | ## Let's Encrypt registration | ||
- | The plugin automatically process your Let's Encrypt account registration, using the administrator email address that you | + | The plugin automatically process your Let's Encrypt account registration, using |
- | have provided during i-MSCP setup phase. If you need change that email after while, you must not forget to run the | + | the administrator email address that you have provided during i-MSCP setup |
- | following command to update your Let's Encrypt account: | + | 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-auto register --update-registration --email <new_email> | + | ``` |
+ | certbot register --update-registration --email <new_email> | ||
+ | ``` | ||
where `<new_email>` is your new email address. | 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 | + | If you don't do so, a new account will be created using the new email address |
- | certificate lineages, making the plugin unable to work properly. | + | and there will be inconsistencies with SSL certificate lineages, making the |
+ | plugin unable to work properly. | ||
## Let's Encrypt Rate Limits | ## Let's Encrypt Rate Limits | ||
Line 86: | Line 92: | ||
Be sure to read https://letsencrypt.org/docs/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 | + | Note that when the Let's Encrypt limits are reached, the plugin will |
- | to `pending`. The pending tasks are postponed as long as the limits are not released. | + | 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) | ## 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: | + | 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 | + | - 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 | - 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. | + | - 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. | + | The link for accessing the administrator's Let's Encrypt interface is available |
+ | in the `System tools` section. | ||
### Note for PanelRedirect plugin users | ### 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 | + | If you use the `PanelRedirect` plugin, you must ensure that you have a version |
- | domain validations will fail. | + | 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 | + | You can enable support for alternative URLs by setting the `include_altnames` |
- | plugin configuration file. Once done, don't forget to trigger a plugin list update. | + | 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. | Be aware that this parameters acts only for new SSL certificate issuances. | ||
Line 113: | Line 125: | ||
### 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 | + | Due to the current Let's Encrypt rate limits, it is not recommended to enable |
- | issuance for which a SAN is added for an alternative URL will possibly hits the `Certificate per Registered Domain` | + | this feature. Indeed, each SSL certificate issuance for which a SAN is added |
- | limit (20 per week) for the control panel domain. This explain why this feature is turned off by default. | + | 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 | + | Note that alternative URLs as provided by i-MSCP are meant to allow the |
- | propagation time. These URLs should not be exposed publicly. | + | 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 | + | You can translate this plugin using a gettext translation editor such as |
- | the `./l10n` directory, inside of the plugin archive. Once translated you can send us your translation file (po file) | + | `Poedit`. Translation files are located under the `./l10n` directory, inside of |
- | for integration in future release. | + | 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 | + | Note that if no translation file exists for your localization in the |
- | from the `l10n/LetsEncrypt.pot` file. Be aware that your file must be `UTF-8`, else, it won't be accepted. | + | `./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 | ## License | ||
Line 145: | Line 162: | ||
- [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> | </markdown> |