# Table of Contents
- [Table of Contents](#table-of-contents)
- [a2utils](#a2utils)
- [Installation](#installation)
- [CLI utilities](#cli-utilities)
- [a2vhost](#a2vhost)
- [a2conf](#a2conf)
- [a2certbot](#a2certbot)
- [Requesting new certificate and troubleshooting](#requesting-new-certificate-and-troubleshooting)
- [Troubleshooting renew certificates](#troubleshooting-renew-certificates)
- [a2certbot warnings (false positives)](#a2certbot-warnings-false-positives)
- [a2certbotssh](#a2certbotssh)
- [a2okerr](#a2okerr)
# a2utils
Package consist of few CLI utilities (based on [a2conf](https://github.com/yaroslaff/a2conf) library)
- `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 easily
- `a2vhost` - manipulate apache2 VirtualHosts
- `a2okerr` - generate indicators for SSL VirtualHosts in [okerr](https://okerr.com/) monitoring system.
Why a2utils is so great?
You can create VirtualHost right from shell:
~~~~
a2vhost --basic -d example.com www.example.com --auto
~~~~
or 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 --auto
~~~
See all SSLCertificateFile directives for vhosts which has SSLEngine On
~~~
a2conf --cmd sslcertificatefile --filter sslengine on
~~~
See 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.txt
~~~
Which way is easier and error-prone to request certificate?
~~~
a2certbot --create -d example.com --aliases
~~~
or
~~~~
certbot certonly --webroot -w /var/www/website_1234 -d example.com -d www.example.com -d shop.example.com -d my.example.com
~~~~
a2certbot reads all needed data right from apache config.
# Installation
Usual simple way:
~~~
pip3 install a2utils
~~~
or get sources from git repo:
~~~
git clone https://github.com/yaroslaff/a2utils
~~~
If using git sources (without installing), work from root dir of repo and do `export PYTONPATH=.`
# CLI utilities
## a2vhost
a2vhost 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)
```shell
a2vhost --both -d echo2.sysattack.com echo3.sysattack.com echo4.sysattack.com echo5.sysattack.com --auto
```
`--both` instructs to make both https website (main) and small plain http website to handle letsencrypt verification and redirect to https.
`--auto` auto-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
```shell
# Create files for new site
$ mkdir /var/www/virtual/echo2.sysattack.com
$ echo hello > /var/www/virtual/echo2.sysattack.com/index.html
# Create HTTP VirtualHost and test
$ a2vhost --basic -d echo2.sysattack.com echo3.sysattack.com echo4.sysattack.com -w /var/www/virtual/echo2.sysattack.com -c /etc/apache2/sites-available/echo2.sysattack.com.conf
$ a2ensite echo2.sysattack.com
$ systemctl reload apache2
$ curl http://echo2.sysattack.com/
hello
```
Now, lets make this site HTTPS and make new plain HTTP site which will redirect to secure HTTPS
```shell
# 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 -d echo2.sysattack.com --aliases
# Convert to HTTPS
$ a2vhost --convert -d echo2.sysattack.com
# Make HTTP-to-HTTPS redirection
$ a2vhost --redirect -d echo2.sysattack.com
# Reload
$ systemctl reload apache2
# List all websites
$ a2vhost --list
```
In the end we got this config file
<details>
<summary>/etc/apache2/sites-enabled/echo2.sysattack.com.conf</summary>
```
<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>
```
</details>
Add any directive to any VirtualHost. We will add comment:
```shell
# add directive
sudo bin/a2vhost --add '# This site is main https site' -d echo2.sysattack.com --vhost '*:443'
```
Delete vhost:
```shell
a2vhost --delete --vhost '*:80' -d example.com
```
(you may add `-a /etc/apache2/apache2.conf` and/or `-c /etc/apache2/sites-available/example.com.conf` if your configuration is non-standard)
## a2conf
### Examples <!-- omit in toc -->
For all examples we will use file
[examples/example.conf](https://github.com/yaroslaff/a2conf/raw/master/examples/example.conf).
You can omit this parameter to use default `/etc/apache2/apache2.conf`.
Use `export PYTHONPATH=.` to use module if it's not installed.
Most useful examples:
```shell
$ bin/a2conf examples/example.conf --dump --vhost secure.example.com
# examples/example.conf:15
<VirtualHost *:443>
# SSL site
DocumentRoot /var/www/example
ServerName example.com # .... OUR TEST SITE ....
ServerAlias www.example.com 1.example.com 2.example.com secure.example.com
DirectoryIndex index.html index.htm default.htm index.php
Options -Indexes +FollowSymLinks
SSLEngine On # SSL Enabled for this virtual host
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
SSLCertificateChainFile /etc/letsencrypt/live/example.com/chain.pem
</VirtualHost>
# Only specific commands with --vhost filter
$ bin/a2conf examples/example.conf --vhost www.example.com:443 --cmd documentroot sslcertificatefile
DocumentRoot /var/www/example
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
# Same output achieved with other way of filtering (based on SSLEngine directive)
$ bin/a2conf examples/example.conf --filter sslengine on --cmd documentroot sslcertificatefile
DocumentRoot /var/www/example
SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
# All hostnames configured in this config file
$ bin/a2conf examples/example.conf --cmd servername serveralias --uargs
secure.example.com example.com www.example.com 2.example.com 1.example.com
# per-vhost summary with filtering
$ bin/a2conf examples/example.conf --cmd servername serveralias --vhfmt 'Host: {servername} Root: {documentroot} Cert: {sslcertificatefile}' --filter sslcertificatefile
Host: example.com Root: /var/www/example Cert: /etc/letsencrypt/live/example.com/fullchain.pem
```
You can get list of all available tokens for `--vhfmt` option in verbose mode (`-v` option).
## a2certbot
a2certbot utility used to quickly detect common [LetsEncrypt](https://letsencrypt.org/) configuration 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 verification
- DNS record points to other host or not exists at all
- And **ANY OTHER** problem (such as using wrong certificate path in apache or whatever). `a2certbot`
simulates HTTP verification (If LetsEncrypt verification fails, `a2certbot` will 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 hit [failed validation limit](https://letsencrypt.org/docs/rate-limits/)
(*5 failures per account, per hostname, per hour* at moment) and will not be blacklisted on LetsEncrypt site.
### Requesting new certificate and troubleshooting
Before requesting new certificates:
```shell
# Verify configuration for website for which you want to request certificate for first time.
bin/a2certbot --prepare -w /var/www/virtual/static.okerr.com/ -d static.okerr.com
=== manual ===
Info:
(static.okerr.com) is local 37.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/ matches LetsEncrypt and Apache
(static.okerr.com) Simulated check match root: /var/www/virtual/static.okerr.com/
---
# You can verify all hostnames for site
bin/a2certbot --prepare -w /var/www/virtual/static.okerr.com/ -d static.okerr.com -d static2.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 -d static.okerr.com --aliases
```
a2certbot 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 certificates
If `certbot renew` fails:
```shell
# Check (verify) ALL existing LetsEncrypt certificates (to check why 'certbot renew' may fail ):
root@bravo:/home/xenon# a2certbot
=== /etc/letsencrypt/renewal/bravo.okerr.com.conf PROBLEM ===
Info:
(bravo.okerr.com) Vhost: /etc/apache2/sites-enabled/okerr.conf:17
LetsEncrypt conf file: /etc/letsencrypt/renewal/bravo.okerr.com.conf
bravo.okerr.com is local 37.59.102.26
Problems:
No DocumentRoot in vhost at /etc/apache2/sites-enabled/okerr.conf:17
---
# Verify only one certificate
root@bravo:/home/xenon# a2certbot --host bravo.okerr.com
=== /etc/letsencrypt/renewal/bravo.okerr.com.conf PROBLEM ===
Info:
(bravo.okerr.com) Vhost: /etc/apache2/sites-enabled/okerr.conf:17
LetsEncrypt conf file: /etc/letsencrypt/renewal/bravo.okerr.com.conf
bravo.okerr.com is local 37.59.102.26
Problems:
No DocumentRoot in vhost at /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 from `certbot renew` may 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.
## a2certbotssh
`a2certbotssh` is 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.com
~~~
With this command it will run `certbot certonly --manual ...` using itself as hooks, to place (and cleanup) validation hooks on remote machine. If `--aliases` given, it will request all aliases for this virtualhost. For example, also www.example.com and new.example.com. If `--test-cert` is given, staging server is used (staging server has much higher rate limits, useful for testing)
## a2okerr
a2okerr is useful only if you are using [okerr](https://okerr.com/): free and open source hybrid (host/network) monitoring system.
[Okerr](https://okerr.com/) is like [nagios](https://www.nagios.org/) or [zabbix](https://www.zabbix.com/), 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 (like https://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), supports [Telegram](https://telegram.org/) and 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
from [okerr git repository](https://gitlab.com/yaroslaff/okerr-dev/).
You will need to install small [okerrupdate](https://gitlab.com/yaroslaff/okerrupdate) package 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.
```shell
# 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 description
a2okerr --prefix my:prefix: --policy Hourly --desc "I love okerr and a2okerr"
# do not really create indicators, just dry run
a2okerr --dry
```
Raw data
{
"_id": null,
"home_page": "https://github.com/yaroslaff/a2utils",
"name": "a2utils",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": "",
"keywords": "",
"author": "Yaroslav Polyakov",
"author_email": "yaroslaff@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/8c/50/cbabe2c701fc6c4c8fbbd46e5cc5a54f3cf4b7d73a054a323bd7764ecf8f/a2utils-0.0.32.tar.gz",
"platform": null,
"description": "# Table of Contents \n- [Table of Contents](#table-of-contents)\n- [a2utils](#a2utils)\n- [Installation](#installation)\n- [CLI utilities](#cli-utilities)\n - [a2vhost](#a2vhost)\n - [a2conf](#a2conf)\n - [a2certbot](#a2certbot)\n - [Requesting new certificate and troubleshooting](#requesting-new-certificate-and-troubleshooting)\n - [Troubleshooting renew certificates](#troubleshooting-renew-certificates)\n - [a2certbot warnings (false positives)](#a2certbot-warnings-false-positives)\n - [a2certbotssh](#a2certbotssh)\n - [a2okerr](#a2okerr)\n\n\n# a2utils \n\nPackage consist of few CLI utilities (based on [a2conf](https://github.com/yaroslaff/a2conf) library)\n\n- `a2conf` - query apache2 config (e.g. get DocumentRoot or get all hostnames for specific VirtualHost)\n- `a2certbot` - diagnose problems with Apache2 VirtualHost and LetsEncrypt certificates and make SSL sites easily\n- `a2vhost` - manipulate apache2 VirtualHosts\n- `a2okerr` - generate indicators for SSL VirtualHosts in [okerr](https://okerr.com/) monitoring system.\n\nWhy a2utils is so great? \n\nYou can create VirtualHost right from shell:\n~~~~\na2vhost --basic -d example.com www.example.com --auto\n~~~~\n\nor even better (create pair of http and https hosts with default auto-guessed settings and LetsEncrypt certificate):\n~~~\na2vhost --both -d example.com www.example.com --auto\n~~~\n\nSee all SSLCertificateFile directives for vhosts which has SSLEngine On\n~~~\na2conf --cmd sslcertificatefile --filter sslengine on\n~~~\n\nSee all sites and documentroot for them (better then apache2ctl -S)\n~~~\na2conf --vhfmt '{vhostargs} {servername} {documentroot}'\n~~~\n\nIf you created/deleted apache vhosts, but have orphaned LE certificates:\n~~~\na2conf --cmd sslcertificatefile| cut -f 2 -d\" \" | sort | uniq > /tmp/apache-certs.txt\nfind /etc/letsencrypt/live/ -name fullchain.pem|sort > /tmp/le-certs.txt\ndiff /tmp/apache-certs.txt /tmp/le-certs.txt\n~~~\n\nWhich way is easier and error-prone to request certificate?\n~~~\na2certbot --create -d example.com --aliases\n~~~\nor\n~~~~\ncertbot certonly --webroot -w /var/www/website_1234 -d example.com -d www.example.com -d shop.example.com -d my.example.com\n~~~~\na2certbot reads all needed data right from apache config. \n\n# Installation\nUsual simple way:\n~~~\npip3 install a2utils\n~~~\n\nor get sources from git repo:\n~~~\ngit clone https://github.com/yaroslaff/a2utils\n~~~\nIf using git sources (without installing), work from root dir of repo and do `export PYTONPATH=.`\n\n\n# CLI utilities\n\n## a2vhost\n\na2vhost is utility to create new http/https websites from CLI. Easy to use from your scripts.\n\nExample uses hosts echoN.sysattack.com, but you should test with your hostname(s).\n\nMighty one-liner: create HTTP/HTTPS websites (http will redirect to https), obtain certificate for https. (as root)\n\n```shell\na2vhost --both -d echo2.sysattack.com echo3.sysattack.com echo4.sysattack.com echo5.sysattack.com --auto\n```\n`--both` instructs to make both https website (main) and small plain http website to handle letsencrypt verification and redirect to https.\n\n`--auto` auto-detects virtualhost config file name (you may override with `-c`) and guesses and creates webroot directory if it's missing (override with `-w`)\n\nFollowing commands will make similar job step-by-step and without `--auto`:\n\nCreate basic HTTP website\n```shell\n# Create files for new site\n$ mkdir /var/www/virtual/echo2.sysattack.com\n$ echo hello > /var/www/virtual/echo2.sysattack.com/index.html\n\n# Create HTTP VirtualHost and test\n$ a2vhost --basic -d echo2.sysattack.com echo3.sysattack.com echo4.sysattack.com -w /var/www/virtual/echo2.sysattack.com -c /etc/apache2/sites-available/echo2.sysattack.com.conf\n$ a2ensite echo2.sysattack.com\n$ systemctl reload apache2\n$ curl http://echo2.sysattack.com/\nhello\n```\n\nNow, lets make this site HTTPS and make new plain HTTP site which will redirect to secure HTTPS\n```shell\n# 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.\n$ a2certbot --create -d echo2.sysattack.com --aliases\n\n# Convert to HTTPS\n$ a2vhost --convert -d echo2.sysattack.com\n\n# Make HTTP-to-HTTPS redirection\n$ a2vhost --redirect -d echo2.sysattack.com\n\n# Reload\n$ systemctl reload apache2\n\n# List all websites\n$ a2vhost --list\n```\n\nIn the end we got this config file \n<details>\n<summary>/etc/apache2/sites-enabled/echo2.sysattack.com.conf</summary>\n\n```\n <VirtualHost *:443> \n ServerName echo2.sysattack.com \n ServerAlias echo3.sysattack.com echo4.sysattack.com echo5.sysattack.com \n DocumentRoot /var/www/virtual/echo2.sysattack.com \n\n SSLEngine On \n SSLCertificateFile /etc/letsencrypt/live/echo2.sysattack.com/fullchain.pem \n SSLCertificateKeyFile /etc/letsencrypt/live/echo2.sysattack.com/privkey.pem \n Header always set Strict-Transport-Security \"max-age=31536000; includeSubDomains\" \n </VirtualHost> \n\n # auto-generated plain HTTP site for redirect\n <VirtualHost *:80> \n ServerName echo2.sysattack.com \n ServerAlias echo3.sysattack.com echo4.sysattack.com echo5.sysattack.com \n DocumentRoot /var/www/virtual/echo2.sysattack.com \n RewriteEngine On \n RewriteCond %{HTTPS} !=on \n RewriteCond %{REQUEST_URI} !^/\\.well\\-known \n RewriteRule (.*) https://%{SERVER_NAME}$1 [R=301,L] \n </VirtualHost> \n```\n</details>\n\nAdd any directive to any VirtualHost. We will add comment:\n```shell\n# add directive\nsudo bin/a2vhost --add '# This site is main https site' -d echo2.sysattack.com --vhost '*:443'\n```\n\nDelete vhost:\n```shell\na2vhost --delete --vhost '*:80' -d example.com\n```\n(you may add `-a /etc/apache2/apache2.conf` and/or `-c /etc/apache2/sites-available/example.com.conf` if your configuration is non-standard)\n\n## a2conf\n### Examples <!-- omit in toc -->\n\nFor all examples we will use file \n[examples/example.conf](https://github.com/yaroslaff/a2conf/raw/master/examples/example.conf).\nYou can omit this parameter to use default `/etc/apache2/apache2.conf`.\n\nUse `export PYTHONPATH=.` to use module if it's not installed.\n\nMost useful examples:\n```shell\n$ bin/a2conf examples/example.conf --dump --vhost secure.example.com \n# examples/example.conf:15\n<VirtualHost *:443> \n # SSL site\n DocumentRoot /var/www/example \n ServerName example.com # .... OUR TEST SITE ....\n ServerAlias www.example.com 1.example.com 2.example.com secure.example.com \n DirectoryIndex index.html index.htm default.htm index.php \n Options -Indexes +FollowSymLinks \n SSLEngine On # SSL Enabled for this virtual host\n SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem \n SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem \n SSLCertificateChainFile /etc/letsencrypt/live/example.com/chain.pem \n</VirtualHost> \n\n# Only specific commands with --vhost filter\n$ bin/a2conf examples/example.conf --vhost www.example.com:443 --cmd documentroot sslcertificatefile \nDocumentRoot /var/www/example\nSSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem\n\n# Same output achieved with other way of filtering (based on SSLEngine directive)\n$ bin/a2conf examples/example.conf --filter sslengine on --cmd documentroot sslcertificatefile\nDocumentRoot /var/www/example\nSSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem\n\n# All hostnames configured in this config file\n$ bin/a2conf examples/example.conf --cmd servername serveralias --uargs\nsecure.example.com example.com www.example.com 2.example.com 1.example.com\n\n# per-vhost summary with filtering\n$ bin/a2conf examples/example.conf --cmd servername serveralias --vhfmt 'Host: {servername} Root: {documentroot} Cert: {sslcertificatefile}' --filter sslcertificatefile\nHost: example.com Root: /var/www/example Cert: /etc/letsencrypt/live/example.com/fullchain.pem\n```\n\nYou can get list of all available tokens for `--vhfmt` option in verbose mode (`-v` option).\n\n## a2certbot\na2certbot utility used to quickly detect common [LetsEncrypt](https://letsencrypt.org/) configuration errors such as:\n- DocumentRoot mismatch between VirtualHost and LetsEncrypt renew config file (e.g. if someone moved site content)\n- RewriteRule or Redirect apache directives preventing verification\n- DNS record points to other host or not exists at all\n- And **ANY OTHER** problem (such as using wrong certificate path in apache or whatever). `a2certbot` \nsimulates HTTP verification (If LetsEncrypt verification fails, `a2certbot` will fail too, and vice versa).\n\na2certbot does not calls LetsEncrypt servers for verification, so if you will use a2certbot to verify your \nconfiguration, you will not hit [failed validation limit](https://letsencrypt.org/docs/rate-limits/) \n(*5 failures per account, per hostname, per hour* at moment) and will not be blacklisted on LetsEncrypt site.\n\n### Requesting new certificate and troubleshooting\n\nBefore requesting new certificates:\n```shell\n# Verify configuration for website for which you want to request certificate for first time.\nbin/a2certbot --prepare -w /var/www/virtual/static.okerr.com/ -d static.okerr.com\n=== manual ===\nInfo:\n (static.okerr.com) is local 37.59.102.26\n (static.okerr.com) Vhost: /etc/apache2/sites-enabled/static.okerr.com.conf:1\n (static.okerr.com) DocumentRoot: /var/www/virtual/static.okerr.com/\n (static.okerr.com) DocumentRoot /var/www/virtual/static.okerr.com/ matches LetsEncrypt and Apache\n (static.okerr.com) Simulated check match root: /var/www/virtual/static.okerr.com/\n---\n\n# You can verify all hostnames for site\nbin/a2certbot --prepare -w /var/www/virtual/static.okerr.com/ -d static.okerr.com -d static2.okerr.com\n\n# ... and finally simple main all-in-one command, it guesses aliases and root (command below does same as command above):\nbin/a2certbot --prepare -d static.okerr.com --aliases\n```\n\na2certbot can generate letsencrypt certificates in simple way (automatically detecting all aliases and \nDocumentRoot, but you can use -d instead of --aliases):\n```\nroot@bravo:/home/xenon# a2certbot --create -d static.okerr.com --aliases\nCreate cert for static.okerr.com\nRUNNING: certbot certonly --webroot -w /var/www/virtual/static.okerr.com/ -d static.okerr.com -d static2.okerr.com\nSaving debug log to /var/log/letsencrypt/letsencrypt.log\nPlugins selected: Authenticator webroot, Installer None\nObtaining a new certificate\nPerforming the following challenges:\nhttp-01 challenge for static2.okerr.com\nUsing the webroot path /var/www/virtual/static.okerr.com for all unmatched domains.\nWaiting for verification...\nCleaning up challenges\n\nIMPORTANT NOTES:\n - Congratulations! Your certificate and chain have been saved at:\n...\n```\n\n### Troubleshooting renew certificates\n\nIf `certbot renew` fails:\n```shell\n# Check (verify) ALL existing LetsEncrypt certificates (to check why 'certbot renew' may fail ):\nroot@bravo:/home/xenon# a2certbot \n=== /etc/letsencrypt/renewal/bravo.okerr.com.conf PROBLEM ===\nInfo:\n (bravo.okerr.com) Vhost: /etc/apache2/sites-enabled/okerr.conf:17\n LetsEncrypt conf file: /etc/letsencrypt/renewal/bravo.okerr.com.conf\n bravo.okerr.com is local 37.59.102.26\nProblems:\n No DocumentRoot in vhost at /etc/apache2/sites-enabled/okerr.conf:17\n---\n\n# Verify only one certificate \nroot@bravo:/home/xenon# a2certbot --host bravo.okerr.com\n=== /etc/letsencrypt/renewal/bravo.okerr.com.conf PROBLEM ===\nInfo:\n (bravo.okerr.com) Vhost: /etc/apache2/sites-enabled/okerr.conf:17\n LetsEncrypt conf file: /etc/letsencrypt/renewal/bravo.okerr.com.conf\n bravo.okerr.com is local 37.59.102.26\nProblems:\n No DocumentRoot in vhost at /etc/apache2/sites-enabled/okerr.conf:17\n---\n```\n\n\n### a2certbot warnings (false positives)\na2certbot expects that requests to .well-known directory of HTTP (port 80) virtualhost must not be redirected.\nIf you have redirection like this: `Redirect 301 / https://example.com/` it will report problem:\n```\nProblems:\n Requests will be redirected: Redirect 301 / https://www.example.com/\n```\n\nActually, this could be OK (false positive) and real verification from `certbot renew` may pass (if https \nsite has same DocumentRoot). To see if this is real problem or not see result for 'Simulated check'. \nIf simulated check matches - website will pass certbot verification. \n\nTo avoid such false positive, do not use such 'blind' redirection, better use this:\n```\n RewriteCond %{REQUEST_URI} !^/\\.well\\-known \n RewriteRule (.*) https://%{SERVER_NAME}$1 [R=301,L]\n```\nThis code in `<VirtuaHost *:80>` context will redirect all requests to HTTPS site EXCEPT LetsEncrypt verification \nrequests.\n\n## a2certbotssh\n\n`a2certbotssh` is wrapper to get certificates using remote machines for verification. Remote machine must have a2utils installed.\n**Example:**\n(any machine):\n~~~\nbin/a2certbotssh --aliases --ssh root@example.com -d example.com\n~~~\nWith this command it will run `certbot certonly --manual ...` using itself as hooks, to place (and cleanup) validation hooks on remote machine. If `--aliases` given, it will request all aliases for this virtualhost. For example, also www.example.com and new.example.com. If `--test-cert` is given, staging server is used (staging server has much higher rate limits, useful for testing)\n\n\n## a2okerr\na2okerr is useful only if you are using [okerr](https://okerr.com/): free and open source hybrid (host/network) monitoring system. \n\n[Okerr](https://okerr.com/) is like [nagios](https://www.nagios.org/) or [zabbix](https://www.zabbix.com/), but can perform network checks \nfrom remote locations, has tiny and optional local client which can run from cron, has powerful logical\nindicators (notify me only if more then 2 servers are dead, notify me if any problem is not fixed for more then 30 minutes, ...), \npublic status pages (like https://status.io/ but free), fault-tolerant sites \n(okerr will redirect dynamic DNS record to backup server if main server is dead, and point it back to main server\n when it's OK), supports [Telegram](https://telegram.org/) and has many other nice features. \n\nYou can use it as free service (like wordpress or gmail) or you can install okerr server on your own linux machine \nfrom [okerr git repository](https://gitlab.com/yaroslaff/okerr-dev/).\n\nYou will need to install small [okerrupdate](https://gitlab.com/yaroslaff/okerrupdate) package to use a2okerr: `pip3 install okerrupdate`.\n\na2okerr discovers all https sites from apache config and creates SSL-indicator in your okerr project \nfor each website. You will get alert message to email and/or telegram if any of your https sites has any problem \n(certificate is not updated in time for any reason and will expire soon or already expired. \nWebsite unavailable for any reason). If you have linux server or website - you need okerr.\n\n```shell\n# Create indicator for all local https websites. If indicator already exists, HTTP error 400 will be received - this is OK.\na2okerr\n\n# alter prefix, policy and description\na2okerr --prefix my:prefix: --policy Hourly --desc \"I love okerr and a2okerr\"\n\n# do not really create indicators, just dry run\na2okerr --dry\n```\n\n\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "apache2 config file utilities",
"version": "0.0.32",
"project_urls": {
"Homepage": "https://github.com/yaroslaff/a2utils"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "557beb98c65f0ebed09d5ac33e971c97059503f4f18de400fd179e6680f7bbec",
"md5": "0c005a11555bafe3dd75ed949e47ca5f",
"sha256": "c54b021bdcf0e3386654f03087705023c95f52ad5b1fea41acc3a712daa424d1"
},
"downloads": -1,
"filename": "a2utils-0.0.32-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0c005a11555bafe3dd75ed949e47ca5f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 21251,
"upload_time": "2023-08-01T12:26:39",
"upload_time_iso_8601": "2023-08-01T12:26:39.768114Z",
"url": "https://files.pythonhosted.org/packages/55/7b/eb98c65f0ebed09d5ac33e971c97059503f4f18de400fd179e6680f7bbec/a2utils-0.0.32-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8c50cbabe2c701fc6c4c8fbbd46e5cc5a54f3cf4b7d73a054a323bd7764ecf8f",
"md5": "259f09387c5ff304367c895e80a4d28a",
"sha256": "adf0076894b754cc0036a043cd9b6b1f402c8895c680767ea55b8a826aae6d7a"
},
"downloads": -1,
"filename": "a2utils-0.0.32.tar.gz",
"has_sig": false,
"md5_digest": "259f09387c5ff304367c895e80a4d28a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 21292,
"upload_time": "2023-08-01T12:26:41",
"upload_time_iso_8601": "2023-08-01T12:26:41.201361Z",
"url": "https://files.pythonhosted.org/packages/8c/50/cbabe2c701fc6c4c8fbbd46e5cc5a54f3cf4b7d73a054a323bd7764ecf8f/a2utils-0.0.32.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-01 12:26:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yaroslaff",
"github_project": "a2utils",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "a2utils"
}
JSON
