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 [2016/05/14 17:14] theemstra |
plugins:letsencrypt [2017/09/13 23:37] nuxwin |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | ======Let's Encrypt Plugin Documentation====== | + | <WRAP center round important 60%> |
+ | **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> | ||
- | This plugin allows the generation and regeneration of Let's Encrypt certificates for use in i-MSCP. | + | <markdown> |
+ | # i-MSCP LetsEncrypt plugin | ||
- | This is a paid plugin, so it's not available for free like many other plugins. | + | ## Introduction |
- | ===== Requirements ===== | + | Provides free SSL certificates through the Let's Encrypt CA. |
- | * i-MSCP versions 1.3.x | + | ## Requirements |
- | ===== Installation ===== | + | - i-MSCP Serie ≥ 1.4.x |
- | **1. Get the latest plugin version from Plugin Store** | + | ## Installation |
- | http://i-mscp.net/filebase/index.php/Filebase/ | + | 1. Be sure that all requirements as stated in the requirements section are met |
- | + | 2. Upload the plugin through the plugin management interface | |
- | **2. Plugin upload and installation** | + | 3. Edit the plugin configuration file according your needs |
+ | 4. Install the plugin through the plugin management interface | ||
- | * Login into the panel as admin and go to the plugin management interface | + | Note that the plugin installation can take up several minutes. |
- | * Upload the plugin archive | + | |
- | * Install the plugin | + | |
- | ===== Update ===== | + | ## Update |
- | **1. Get the plugin from Plugin Store** | + | 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 | ||
- | http://i-mscp.net/filebase/index.php/Filebase/ | + | Note that the plugin update can take up several minutes. |
- | **2. Backup your current plugin config** | + | ### Restore you plugin configuration file if needed |
- | # plugins/LetsEncrypt/config.php | + | 1. Restore your plugin configuration file (compare it with the new version first) |
- | + | 2. Update the plugin list through the plugin management interface | |
- | **3. Plugin upload and update** | + | |
- | * Login into the panel as admin and go to the plugin management interface | + | ## Plugin deactivation/uninstallation |
- | * Upload the new plugin archive | + | |
- | * Update the plugin list | + | |
- | ===== Configuration ===== | + | 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 can configure this plugin to your needs. | + | According to the previous sentence, It must be noted that the current actions |
- | Check out the config.php in the plugin archive. | + | for SSL certificates that are displayed in the interface, at customer and |
+ | administrator levels, do not predict the action that will actually take place. | ||
- | Configuration values include: | + | 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. | ||
- | **1. Command (and location) of the letsencrypt client | + | ## Manual execution of the Certbot client |
- | **2. Period before expiration, certificates will be renewed (default: 30 days before) | + | 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). | ||
- | **3. Waiting time for retry if certificate status is pending (default: 1 hour) | + | 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. | ||
- | **4. Path to created certificates | + | ## Certbot client version |
- | **5. Additional command line options passed-in to letsencrypt while creating certificate | + | 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. | ||
- | **6. Additional command line options passed-in to letsencrypt while revoking certificate | + | ## Let's Encrypt registration |
- | **7. Cronjob for renewing certificates (default: run once per day) | + | 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> |