Package: a2utils
Table of ContentsTable of Contentsa2utilsInstallationCLI utilitiesa2vhosta2confa2certbotRequesting new certificate and troubleshootingTroubleshooting renew certificatesa2certbot warnings (false positives)a2certbotssha2okerra2utilsPackage consist of few CLI utilities (based ona2conflibrary)a2conf-  query apache2 config (e.g. get DocumentRoot or get all hostnames for specific VirtualHost)a2certbot- diagnose problems with Apache2 VirtualHost and LetsEncrypt certificates and make SSL sites easilya2vhost- manipulate apache2 VirtualHostsa2okerr- generate indicators for SSL VirtualHosts inokerrmonitoring system.Why a2utils is so great?You can create VirtualHost right from shell:a2vhost --basic -d example.com www.example.com --autoor even better (create pair of http and https hosts with default auto-guessed settings and LetsEncrypt certificate):a2vhost --both -d example.com www.example.com --autoSee all SSLCertificateFile directives for vhosts which has SSLEngine Ona2conf --cmd sslcertificatefile  --filter sslengine onSee all sites and documentroot for them (better then apache2ctl -S)a2conf --vhfmt '{vhostargs} {servername} {documentroot}'If you created/deleted apache vhosts, but have orphaned LE certificates:a2conf --cmd sslcertificatefile| cut -f 2 -d" " | sort | uniq > /tmp/apache-certs.txt
find /etc/letsencrypt/live/ -name fullchain.pem|sort > /tmp/le-certs.txt
diff /tmp/apache-certs.txt /tmp/le-certs.txtWhich way is easier and error-prone to request certificate?a2certbot --create -d example.com --aliasesorcertbot certonly --webroot -w /var/www/website_1234 -d example.com -d www.example.com -d shop.example.com -d my.example.coma2certbot reads all needed data right from apache config.InstallationUsual simple way:pip3 install a2utilsor get sources from git repo:git clone https://github.com/yaroslaff/a2utilsIf using git sources (without installing), work from root dir of repo and doexport PYTONPATH=.CLI utilitiesa2vhosta2vhost is utility to create new http/https websites from CLI. Easy to use from your scripts.Example uses hosts echoN.sysattack.com, but you should test with your hostname(s).Mighty one-liner: create HTTP/HTTPS websites (http will redirect to https), obtain certificate for https. (as root)a2vhost--both-decho2.sysattack.comecho3.sysattack.comecho4.sysattack.comecho5.sysattack.com--auto--bothinstructs to make both https website (main) and small plain http website to handle letsencrypt verification and redirect to https.--autoauto-detects virtualhost config file name (you may override with-c) and guesses and creates webroot directory if it's missing (override with-w)Following commands will make similar job step-by-step and without--auto:Create basic HTTP website# Create files for new site$mkdir/var/www/virtual/echo2.sysattack.com
$echohello>/var/www/virtual/echo2.sysattack.com/index.html# Create HTTP VirtualHost and test$a2vhost--basic-decho2.sysattack.comecho3.sysattack.comecho4.sysattack.com-w/var/www/virtual/echo2.sysattack.com-c/etc/apache2/sites-available/echo2.sysattack.com.conf
$a2ensiteecho2.sysattack.com
$systemctlreloadapache2
$curlhttp://echo2.sysattack.com/
helloNow, lets make this site HTTPS and make new plain HTTP site which will redirect to secure HTTPS# Generate LetsEncrypt certificate. Yes, thats very simple. We do not need --alises for this vhost, but we may need it if VirtualHost has ServerAlias'es and we want certificates for them.$a2certbot--create-decho2.sysattack.com--aliases# Convert to HTTPS$a2vhost--convert-decho2.sysattack.com# Make HTTP-to-HTTPS redirection$a2vhost--redirect-decho2.sysattack.com# Reload$systemctlreloadapache2# List all websites$a2vhost--listIn the end we got this config file/etc/apache2/sites-enabled/echo2.sysattack.com.conf<VirtualHost *:443> 
    ServerName echo2.sysattack.com 
    ServerAlias echo3.sysattack.com echo4.sysattack.com echo5.sysattack.com 
    DocumentRoot /var/www/virtual/echo2.sysattack.com 

    SSLEngine On 
    SSLCertificateFile /etc/letsencrypt/live/echo2.sysattack.com/fullchain.pem 
    SSLCertificateKeyFile /etc/letsencrypt/live/echo2.sysattack.com/privkey.pem 
    Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains" 
  </VirtualHost> 

  # auto-generated plain HTTP site for redirect
  <VirtualHost *:80> 
    ServerName echo2.sysattack.com 
    ServerAlias echo3.sysattack.com echo4.sysattack.com echo5.sysattack.com 
    DocumentRoot /var/www/virtual/echo2.sysattack.com 
    RewriteEngine On 
    RewriteCond %{HTTPS} !=on 
    RewriteCond %{REQUEST_URI} !^/\.well\-known 
    RewriteRule (.*) https://%{SERVER_NAME}$1 [R=301,L] 
  </VirtualHost>Add any directive to any VirtualHost. We will add comment:# add directivesudobin/a2vhost--add'# This site is main https site'-decho2.sysattack.com--vhost'*:443'Delete vhost:a2vhost--delete--vhost'*:80'-dexample.com(you may add-a /etc/apache2/apache2.confand/or-c /etc/apache2/sites-available/example.com.confif your configuration is non-standard)a2confExamplesFor all examples we will use fileexamples/example.conf.
You can omit this parameter to use default/etc/apache2/apache2.conf.Useexport PYTHONPATH=.to use module if it's not installed.Most useful examples:$bin/a2confexamples/example.conf--dump--vhostsecure.example.com# examples/example.conf:15<VirtualHost*:443># SSL siteDocumentRoot/var/www/exampleServerNameexample.com# .... OUR TEST SITE ....ServerAliaswww.example.com1.example.com2.example.comsecure.example.comDirectoryIndexindex.htmlindex.htmdefault.htmindex.phpOptions-Indexes+FollowSymLinksSSLEngineOn# SSL Enabled for this virtual hostSSLCertificateFile/etc/letsencrypt/live/example.com/fullchain.pemSSLCertificateKeyFile/etc/letsencrypt/live/example.com/privkey.pemSSLCertificateChainFile/etc/letsencrypt/live/example.com/chain.pem</VirtualHost># Only specific commands with --vhost filter$bin/a2confexamples/example.conf--vhostwww.example.com:443--cmddocumentrootsslcertificatefileDocumentRoot/var/www/example
SSLCertificateFile/etc/letsencrypt/live/example.com/fullchain.pem# Same output achieved with other way of filtering (based on SSLEngine directive)$bin/a2confexamples/example.conf--filtersslengineon--cmddocumentrootsslcertificatefile
DocumentRoot/var/www/example
SSLCertificateFile/etc/letsencrypt/live/example.com/fullchain.pem# All hostnames configured in this config file$bin/a2confexamples/example.conf--cmdservernameserveralias--uargs
secure.example.comexample.comwww.example.com2.example.com1.example.com# per-vhost summary with filtering$bin/a2confexamples/example.conf--cmdservernameserveralias--vhfmt'Host: {servername} Root: {documentroot} Cert: {sslcertificatefile}'--filtersslcertificatefile
Host:example.comRoot:/var/www/exampleCert:/etc/letsencrypt/live/example.com/fullchain.pemYou can get list of all available tokens for--vhfmtoption in verbose mode (-voption).a2certbota2certbot utility used to quickly detect commonLetsEncryptconfiguration errors such as:DocumentRoot mismatch between VirtualHost and LetsEncrypt renew config file (e.g. if someone moved site content)RewriteRule or Redirect apache directives preventing verificationDNS record points to other host or not exists at allAndANY OTHERproblem (such as using wrong certificate path in apache or whatever).a2certbotsimulates HTTP verification (If LetsEncrypt verification fails,a2certbotwill fail too, and vice versa).a2certbot does not calls LetsEncrypt servers for verification, so if you will use a2certbot to verify your
configuration, you will not hitfailed validation limit(5 failures per account, per hostname, per hourat moment) and will not be blacklisted on LetsEncrypt site.Requesting new certificate and troubleshootingBefore requesting new certificates:# Verify configuration for website for which you want to request certificate for first time.bin/a2certbot--prepare-w/var/www/virtual/static.okerr.com/-dstatic.okerr.com===manual===Info:(static.okerr.com)islocal37.59.102.26(static.okerr.com)Vhost:/etc/apache2/sites-enabled/static.okerr.com.conf:1(static.okerr.com)DocumentRoot:/var/www/virtual/static.okerr.com/(static.okerr.com)DocumentRoot/var/www/virtual/static.okerr.com/matchesLetsEncryptandApache(static.okerr.com)Simulatedcheckmatchroot:/var/www/virtual/static.okerr.com/
---# You can verify all hostnames for sitebin/a2certbot--prepare-w/var/www/virtual/static.okerr.com/-dstatic.okerr.com-dstatic2.okerr.com# ... and finally simple main all-in-one command, it guesses aliases and root (command below does same as command above):bin/a2certbot--prepare-dstatic.okerr.com--aliasesa2certbot can generate letsencrypt certificates in simple way (automatically detecting all aliases and
DocumentRoot, but you can use -d instead of --aliases):root@bravo:/home/xenon# a2certbot --create -d static.okerr.com --aliases
Create cert for static.okerr.com
RUNNING: certbot certonly --webroot -w /var/www/virtual/static.okerr.com/ -d static.okerr.com -d static2.okerr.com
Saving debug log to /var/log/letsencrypt/letsencrypt.log
Plugins selected: Authenticator webroot, Installer None
Obtaining a new certificate
Performing the following challenges:
http-01 challenge for static2.okerr.com
Using the webroot path /var/www/virtual/static.okerr.com for all unmatched domains.
Waiting for verification...
Cleaning up challenges

IMPORTANT NOTES:
 - Congratulations! Your certificate and chain have been saved at:
...Troubleshooting renew certificatesIfcertbot renewfails:# Check (verify) ALL existing LetsEncrypt certificates (to check why 'certbot renew' may fail ):root@bravo:/home/xenon#a2certbot===/etc/letsencrypt/renewal/bravo.okerr.com.confPROBLEM===Info:(bravo.okerr.com)Vhost:/etc/apache2/sites-enabled/okerr.conf:17LetsEncryptconffile:/etc/letsencrypt/renewal/bravo.okerr.com.confbravo.okerr.comislocal37.59.102.26
Problems:NoDocumentRootinvhostat/etc/apache2/sites-enabled/okerr.conf:17
---# Verify only one certificateroot@bravo:/home/xenon#a2certbot--hostbravo.okerr.com===/etc/letsencrypt/renewal/bravo.okerr.com.confPROBLEM===Info:(bravo.okerr.com)Vhost:/etc/apache2/sites-enabled/okerr.conf:17LetsEncryptconffile:/etc/letsencrypt/renewal/bravo.okerr.com.confbravo.okerr.comislocal37.59.102.26
Problems:NoDocumentRootinvhostat/etc/apache2/sites-enabled/okerr.conf:17
---a2certbot warnings (false positives)a2certbot expects that requests to .well-known directory of HTTP (port 80) virtualhost must not be redirected.
If you have redirection like this:Redirect 301 / https://example.com/it will report problem:Problems:
    Requests will be redirected: Redirect 301 / https://www.example.com/Actually, this could be OK (false positive) and real verification fromcertbot renewmay pass (if https
site has same  DocumentRoot). To see if this is real problem or not see result for 'Simulated check'.
If simulated check matches - website will pass certbot verification.To avoid such false positive, do not use such 'blind' redirection, better use this:RewriteCond %{REQUEST_URI} !^/\.well\-known        
      RewriteRule (.*) https://%{SERVER_NAME}$1 [R=301,L]This code in<VirtuaHost *:80>context will redirect all requests to HTTPS site EXCEPT LetsEncrypt verification
requests.a2certbotssha2certbotsshis wrapper to get certificates using remote machines for verification. Remote machine must have a2utils installed.Example:(any machine):bin/a2certbotssh --aliases --ssh root@example.com -d example.comWith this command it will runcertbot certonly --manual ...using itself as hooks, to place (and cleanup) validation hooks on remote machine. If--aliasesgiven, it will request all aliases for this virtualhost. For example, alsowww.example.comand new.example.com. If--test-certis given, staging server is used (staging server has much higher rate limits, useful for testing)a2okerra2okerr is useful only if you are usingokerr: free and open source hybrid (host/network) monitoring system.Okerris likenagiosorzabbix, but can perform network checks
from remote locations, has tiny and optional local client  which can run from cron, has powerful logical
indicators (notify me only if more then 2 servers are dead, notify me if any problem is not fixed for more then 30 minutes, ...),
public status pages (likehttps://status.io/but free), fault-tolerant sites
(okerr will redirect dynamic DNS record to backup server if main server is dead, and point it back to main server
when it's OK), supportsTelegramand has many other nice features.You can use it as free service (like wordpress or gmail) or you can install okerr server on your own linux machine
fromokerr git repository.You will need to install smallokerrupdatepackage to use a2okerr:pip3 install okerrupdate.a2okerr discovers all https sites from apache config and creates SSL-indicator in your okerr project
for each website. You will get alert message to email and/or telegram if any of your https sites has any problem
(certificate is not updated in time for any reason and will expire soon or already expired.
Website unavailable for any reason). If you have linux server or website - you need okerr.# Create indicator for all local https websites. If indicator already exists, HTTP error 400 will be received - this is OK.a2okerr# alter prefix, policy and descriptiona2okerr--prefixmy:prefix:--policyHourly--desc"I love okerr and a2okerr"# do not really create indicators, just dry runa2okerr--dry