-
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
bugfish\bugfishtm
committed
Aug 21, 2024
1 parent
1e19926
commit 80761fa
Showing
28 changed files
with
1,381 additions
and
20 deletions.
There are no files selected for viewing
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,126 @@ | ||
| # Dovecot Certificate Interface [DCI] | ||
|
|
||
| ## Introduction | ||
|
|
||
| Welcome to the documentation for the Dovecot Certificate Interface [DCI]! This software facilitates the management of Dovecot per-domain SSL certificates and is designed to work seamlessly with ISPConfig. It provides a streamlined approach to configuring Dovecot for secure email communications across multiple domains. | ||
|
|
||
| **Key Features:** | ||
| - Manage and control Dovecot per-domain SSL certificates. | ||
| - Automate the ISPConfig Dovecot configuration file generation. | ||
| - Integrate with existing systems with minimal impact. | ||
|
|
||
| **Important:** If another system is already managing Dovecot configuration files (e.g., Plesk), using this software may lead to conflicts. | ||
|
|
||
| For additional resources, you can: | ||
|
|
||
| - [Download the latest release](https://github.com/bugfishtm/Dovecot-Certificate-Interface/archive/refs/heads/main.zip) | ||
| - [Visit the GitHub repository](https://github.com/bugfishtm/Dovecot-Certificate-Interface) | ||
|
|
||
| ## General Information | ||
|
|
||
| The Dovecot Certificate Interface allows for: | ||
| - SSL certificates for each domain used with Dovecot. | ||
| - Automation of certificate configuration with ISPConfig. | ||
| - Deep validation of certificates to ensure their integrity. | ||
|
|
||
| **Note:** This software has been tested primarily on Debian and Ubuntu systems. Compatibility with other systems should be verified individually. | ||
|
|
||
| ## Tutorial Videos | ||
|
|
||
| Introduction Video | ||
| <video width="320" height="240" controls> | ||
| <source src="./introduction.mp4" type="video/mp4"> | ||
| Your browser does not support the video tag. | ||
| </video> | ||
| [Download Video](./introduction.mp4) | [Download Handout](./presentation.pptx) | ||
|
|
||
| Information Video | ||
| <video width="320" height="240" controls> | ||
| <source src="./information.mp4" type="video/mp4"> | ||
| Your browser does not support the video tag. | ||
| </video> | ||
| [Download Video](./information.mp4) | ||
|
|
||
| ## Screenshots | ||
|
|
||
| <div style="display: flex; flex-wrap: wrap; gap: 10px; justify-content: center;"> | ||
| <a href="main.png" target="_blank"> | ||
| <img src="main.png" alt="Screenshot of Domain Panel" style="width: 100%; max-width: 300px; height: auto; border-radius: 5px; box-shadow: 0 2px 5px rgba(0,0,0,0.2);"> | ||
| </a> | ||
| <a href="2.png" target="_blank"> | ||
| <img src="2.png" alt="Screenshot of Blacklisting Feature" style="width: 100%; max-width: 300px; height: auto; border-radius: 5px; box-shadow: 0 2px 5px rgba(0,0,0,0.2);"> | ||
| </a> | ||
| <a href="1.png" target="_blank"> | ||
| <img src="1.png" alt="Screenshot of User Management Panel" style="width: 100%; max-width: 300px; height: auto; border-radius: 5px; box-shadow: 0 2px 5px rgba(0,0,0,0.2);"> | ||
| </a> | ||
| </div> | ||
|
|
||
|
|
||
| ## Project Acknowledgment | ||
|
|
||
| The Dovecot Certificate Interface project was developed using the [Bugfish Framework](./bugfish-framework-banner.jpg). | ||
|
|
||
| ## Requirements | ||
|
|
||
| - **Mailserver:** Dovecot | ||
| - **No Other SSL Management Software:** Ensure no other software is managing per-domain SSL certificates. | ||
| - **Webserver:** PHP 7/8 capable | ||
| - **Database:** MySQL | ||
|
|
||
| ## Compatibility | ||
|
|
||
| The software has been tested on various systems: | ||
|
|
||
| - **Debian:** 8/9/10/11 | ||
| - **Ubuntu:** 16/18/20/22 | ||
| - **Dovecot Versions:** Various (Standalone) | ||
| - **ISPConfig Versions:** Various (Auto-Fetch Domains and SSL Certificates) | ||
|
|
||
| ## System Files Changes | ||
|
|
||
| The DCI software is non-destructive: | ||
|
|
||
| - It modifies only the file specified in `settings.php` with the constant `_CRON_DOVECOT_FILE_`. | ||
| - Additions to the `dovecot.conf` file are reversible. | ||
| - Conflicts with other configuration management tools (e.g., Plesk) should be avoided. | ||
|
|
||
| ## User Management | ||
|
|
||
| Manage users with the following capabilities: | ||
|
|
||
| - Create, edit, and delete users. | ||
| - Assign different permissions for various areas. | ||
| - If the admin password is lost and no other users have access, you must either delete the user database from MySQL or change the admin password directly in the database. | ||
|
|
||
| ## Logging | ||
|
|
||
| Monitor the background operations of cronjobs in the "Logs" section of the web interface: | ||
|
|
||
| - View logs for `sync.php` and `ispconfig-fetch.php`. | ||
| - Latest entries are the most relevant, with older entries available in the archive. | ||
|
|
||
| ## Debugging | ||
|
|
||
| Enable MySQL logging for debugging purposes by setting `_MYSQL_LOGGING_` to "true" in `settings.php`. This will display MySQL errors in a new section of the web interface. This feature is intended for debugging and not for use in production environments. | ||
|
|
||
| ## SSL Validation | ||
|
|
||
| Domains added to the software will be validated before being written to the Dovecot configuration file: | ||
|
|
||
| - **Validation Checks:** The software checks certificate modulus to ensure consistency between certificate and key. | ||
| - **Error Handling:** Domains with invalid certificates or keys will not be added. | ||
|
|
||
| ## Use with ISPConfig | ||
|
|
||
| - **Automation:** The software can automatically create Dovecot configuration files for SSL mail domains by fetching certificates from ISPConfig. | ||
| - **Custom Certificates:** If custom ISPConfig certificates are available, they will be used. | ||
| - **Standalone Mode:** If using ISPConfig, avoid activating the `ispconfig-fetch` cronjob if you want to manage domains manually. | ||
|
|
||
| ## IP Blacklisting | ||
|
|
||
| The software includes an IP blacklisting feature: | ||
|
|
||
| - **Failed Logins:** IP addresses are blocked after a specified number of failed login attempts. | ||
| - **Blocking Duration:** IPs remain blocked until the `daily.php` cronjob is executed or manually removed. | ||
|
|
||
| For further assistance or detailed documentation, please refer to the [GitHub repository](https://github.com/bugfishtm/Dovecot-Certificate-Interface). |
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,81 @@ | ||
| # Software Installation Guide | ||
|
|
||
| ## General Information | ||
|
|
||
| Before deploying the software, review the configuration/settings file for your instance. Ensure that the `settings.php` file is correctly configured. While this software has been successfully used in many production environments, there are no absolute guarantees. | ||
|
|
||
| This software has been tested on Ubuntu and Debian systems, though it may work on other systems that have not been tested. If using a system other than Debian or Ubuntu, you might need to adjust deeper settings within the `settings.php` file. This software is optimized for Debian/Ubuntu with Apache and PHP 8. Below are the requirements and installation steps to follow: | ||
|
|
||
| ## Requirements | ||
|
|
||
| - Root permissions for cronjobs on the system. | ||
| - Apache2 web server with PHP 7/8 support. | ||
| - Apache2 module: `rewrite`. | ||
| - PHP modules: `mysqli`, `curl`, `intl`, `mbstring`, `gd`. | ||
| - MySQL database connection and user credentials (configured in `settings.php`). | ||
|
|
||
| ## Installation Procedure | ||
|
|
||
| 1. **Upload Files**: Upload the files from the "source" directory of this repository to your web space. | ||
| 2. **Configure Settings**: Check the `settings.sample.php` file and make the necessary changes. Set your MySQL login credentials in the `settings.php` file. | ||
| 3. **Rename Configuration File**: Rename `settings.sample.php` to `settings.php`. | ||
| 4. **Automatic SQL Tables**: The software will automatically create any required SQL tables when the website is first opened. An initial user will be created, and login credentials will be provided at the end of this guide. | ||
| 5. **Setup Cronjob**: Configure the cronjob as described below. Without it, Dovecot configuration will not be written. | ||
| 6. **Edit Dovecot Configuration**: It is crucial to modify the `dovecot.conf` file as described in the documentation below. | ||
|
|
||
| ## Initial Setup | ||
|
|
||
| After uploading the project files to the server (outside of the source directory), modify the `settings.sample.php` file as needed and rename it to `settings.php`. This step is mandatory to ensure the software functions correctly, as valid MySQL user data is required. | ||
|
|
||
| ### Configuration Settings | ||
|
|
||
| Below is a list of settings you can configure in the `settings.php` file: | ||
|
|
||
| | Constant | Description | | ||
| |---------------------------------|---------------------------------------------------------------------------------------------------------| | ||
| | `_TITLE_` | Set the website title, which will be shown in your browser tab. | | ||
| | `_IMPRESSUM_` | Link to your impressum page, accessible from the footer. | | ||
| | `_SQL_HOST_` | SQL Database Host. | | ||
| | `_SQL_USER_` | SQL Database User. | | ||
| | `_SQL_PASS_` | SQL Database Password. | | ||
| | `_SQL_DB_` | SQL Database name. | | ||
| | `_IP_BLACKLIST_DAILY_OP_LIMIT_` | IP blacklist limit for blocking IPs (default is 1000). Reset daily if the cronjob `daily.php` is executed. | | ||
| | `_CSRF_VALID_LIMIT_TIME_` | Validity period of a CSRF key for form validation (default is 1000 seconds). | | ||
| | `_MYSQL_LOGGING_` | Set to "true" to enable MySQL logging and the debug area in the web interface. Set to "false" to disable. | | ||
| | `_COOKIES_` | Cookie prefix. No need to change unless you are familiar with the implications. | | ||
| | `_CRON_DOVECOT_FILE_` | Path to the Dovecot configuration file for SSL certificate/domain settings. Include this in `dovecot.conf`. | | ||
| | `_CRON_ISP_FOLDER_SEARCH_` | Path for fetching subfolder names from ISPConfig (only needed if using ISPConfig). | | ||
|
|
||
| ## Cronjob Setup | ||
|
|
||
| To ensure the software operates correctly, configure the following cronjobs: | ||
|
|
||
| ### Mandatory Cronjobs | ||
|
|
||
| | Command | Interval | Description | | ||
| |------------------------------------|----------|-------------------------------------------------------------------------------------------------------| | ||
| | `_webroot_/_cronjob/daily.php` | Daily | Resets blacklisted IPs (optional but recommended). | | ||
| | `_webroot_/_cronjob/sync.php` | X | Executes all domain and Dovecot related operations. Recommended interval: hourly. This is mandatory. | | ||
|
|
||
| ### Optional ISP Config Domain Fetch Cronjob | ||
|
|
||
| | Command | Interval | Description | | ||
| |------------------------------------|----------|-------------------------------------------------------------------------------------------------------| | ||
| | `_webroot_/_cronjob/ispconfig_fetch.php` | X | Fetches SSL certificates and domains from ISPConfig webroot folders. Only needed if using ISPConfig. | | ||
|
|
||
| ## Edit Dovecot Configuration | ||
|
|
||
| **Important:** Modify the `dovecot.conf` file to make the script work. Add the following line to the end of the file: | ||
|
|
||
| ``` | ||
| !include_try dci.certs.conf | ||
| ``` | ||
|
|
||
| ## Initial Login | ||
|
|
||
| After successfully deploying the software, log in with the following credentials: | ||
|
|
||
| - **Username**: admin | ||
| - **Password**: changeme | ||
|
|
||
| **Important:** Change the initial password after the first successful login. |
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| document.addEventListener("DOMContentLoaded", function() { | ||
| const links = document.querySelectorAll('a[href^="http"]'); | ||
| links.forEach(link => { | ||
| link.setAttribute('target', '_blank'); | ||
| link.setAttribute('rel', 'noopener'); | ||
| }); | ||
| }); |
Oops, something went wrong.