From 2d49a44fd824d13d5d5396786a0a0aa617d37146 Mon Sep 17 00:00:00 2001 From: jerrm Date: Sun, 26 Jul 2020 17:11:59 -0400 Subject: [PATCH] Update README --- README.md | 85 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 62 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 6b58611..57bee6c 100644 --- a/README.md +++ b/README.md @@ -21,15 +21,16 @@ Certman and Firewall module updates opens up the firewall automatically. A file watch service monitors the folders FreePBX uses for LetsEncrypt updates. When an update is detected, the service opens up http access in iptables, then closes access when the update files are deleted. The update -process generally takes about 5-10 seconds per certificate. +process generally takes about 5-10 seconds per certificate. -The http pinhole is accomplished by inserting a single rule allowing http +The http pinhole is accomplished by inserting a single rule allowing http access. The rule is automatically deleted once the update is complete. -At no point is iptables disabled or restarted. +Only http port 80 is opened. At no point is iptables disabled or restarted. +All other existing iptables rules remain active. -A 60 second timeout makes sure the door is closed if the update process hangs -for some reason. +A 60 second timeout makes sure the door is closed if the LetsEncrypt update +process hangs for some reason. A nightly cron job is setup to reload Apache if its certificate was updated. @@ -49,58 +50,95 @@ lewatch.sh remove No pre-existing config files are modified by this script. ### Sangoma Distro -If installled under the Sangoma Distro, the script uses the Distro's existing -incrond 0.5._10_ to watch for the file changes associated with a LetsEncrypt -update. No new packages are installed. One config additional file is added +If installled under the Sangoma Distro, the script uses the Distro's existing +incrond 0.5._10_ to watch for the file changes associated with a LetsEncrypt +update. No new packages are installed. One additional config file is added to /etc/incron.d. ### CentOS, Debian, Ubuntu, etc.. -For all other distributions, the script uses _direvent_ to monitor file system -changes. +For all other distributions, the script uses [_direvent_](https://www.gnu.org.ua/software/direvent/) +to monitor file system changes. -The incrond version in the CentOS7 EPEL repo and recent Debian derivatives +The incrond version in the CentOS7 EPEL repo and recent Debian derivatives is 0.5._12_. Unfortunately, incrond 0.5.12 has some pretty nasty bugs. The bugs -would not directly impact this script's functionality, but they are easy to -trigger. It is best not to rely on the 0.5.12 version. +would not directly impact this script's functionality, but they are easy to +trigger. It is best not to rely on the 0.5.12 version. If a working _direvent_ is found it will be used. If not found, the script builds and installs [_direvent_ 5.2](https://www.gnu.org.ua/software/direvent/) -to monitor file system changes. +to monitor file system changes. #### Why not use the Linux distribution's _direvent_ package? CentOS doesn't have a _direvent_ package. The git version built is a few commits ahead of the official 5.2 release and includes fixes worth the build time. -Any packages installed to facilitate building _direvent_ are removed +Any packages installed to facilitate building _direvent_ are removed automatically. The net impact on the running system should be minimal. _If the distribution's direvent package is preferred, install it first._ ## What about Apache? -If using the Sangoma Distro, select the proper certificate under +If using the Sangoma Distro, select the proper certificate under _Admin->System Admin->HTTPS Setup->Settings_ and FreePBX will automatically reload the Apache config as needed. FreePBX does not automatically reload Apache if not using the official Distro. Therefore, this script schedules a nightly cron job to update the running -Apache server. The cron job checks the current in-use certificate against -latest version on disk and reloads Apache if needed. +Apache server. The cron job checks the current in-use certificate against +latest version on disk and reloads Apache if needed. _To disable auto updating, delete the file /etc/cron.d/lewatch-reload-apache._ ### Apache Certificate Location -Updating the Apache config files to use the certman LetsEncrypt certificate is -left to the user. - -The script assumes Apache will use the certificate selected as "default" in +The script assumes Apache will use the certificate selected as "default" in the certman GUI. FreePBX always copies the "default" cert to the location /etc/asterisk/keys/integration, making it simple to reference regardless of host name. -_If another certificate is desired, edit the the script pemPath variable._ +_If another certificate is desired, edit the script pemPath variable._ + +Parsing any potential Apache configuration changes is beyond scope of the +script. Updating the Apache config files to use the certman LetsEncrypt +certificate is left to the user. + +Sample code to update default CentOS7 and Debian configs: +1. *CentOS 7* + ``` + # if mod_ssl is not already enabled then install it + yum -y install mod_ssl + + # point SSLCertificateFile to the FreePBX "default" certificate full chain pem file + sed -i 's|^SSLCertificateFile .*$|SSLCertificateFile /etc/asterisk/keys/integration/certificate.pem|g' /etc/httpd/conf.d/ssl.conf + + # comment out the SSLCertificateKeyFile line as it isn't needed + sed -i '/^SSLCertificateKeyFile/ s/^#*/#/' /etc/httpd/conf.d/ssl.conf + + # restart apache to pick up our changes + systemctl restart httpd + + ``` +2. *Debian Buster* + ``` + # point SSLCertificateFile to the FreePBX "default" certificate full chain pem file + sed -i '/^\s*SSLCertificateFile\s/ s|SSLCertificateFile\s.*$|SSLCertificateFile /etc/asterisk/keys/integration/certificate.pem|g' /etc/apache2/sites-available/default-ssl.conf + + # comment out the SSLCertificateKeyFile line as it isn't needed + sed -i '/^\s*SSLCertificateKeyFile/ s/SSLCertificateKeyFile/#SSLCertificateKeyFile/' /etc/apache2/sites-available/default-ssl.conf + + # enable ssl + a2enmod ssl + a2ensite default-ssl + + # restart apache to pick up our changes + systemctl restart apache2 + ``` + ## Does it have to open all http access? +The default exposure is minimal. The http pinhole is open for less than 10 +seconds in most cases, and then only once every 60 days. + The script as published is intended to "just work" for most any iptables rule set. It can certainly be tweaked to be more restrictive, but it is difficult to be more restrictive in a generic way. Some user customization is required. @@ -124,3 +162,4 @@ LetsEncrypt web folders: ``` rule="INPUT -p tcp --dport 80 -j lefilter -m comment --comment $serviceName" ``` +