**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.**
# i-MSCP LetsEncrypt plugin
Provides free SSL certificates through the Let's Encrypt CA.
## Requirements
- i-MSCP Serie ≥ 1.4.x
## Installation
1. Be sure that all requirements as stated in the requirements section are met
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
Note that the plugin installation can take up several minutes.
## 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
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
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.
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, 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.
## 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 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
```
where `` 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
@copyright (C) 2016-2017 Laurent Declercq
@license i-MSCP License
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")