From b92bd85597a065f7f043b4d22c98e86929ce902f Mon Sep 17 00:00:00 2001
From: Konstantin Demin <rockdrilla@gmail.com>
Date: Fri, 20 Sep 2024 22:51:44 +0300
Subject: [PATCH] doc: update examples

---
 doc/examples/njs/README.md  | 34 +++++++++++++---------
 doc/examples/perl/README.md | 34 +++++++++++++---------
 doc/examples/ssl/README.md  | 57 ++++++++++++++++++++++++++-----------
 3 files changed, 81 insertions(+), 44 deletions(-)

diff --git a/doc/examples/njs/README.md b/doc/examples/njs/README.md
index 9254696..15c2380 100644
--- a/doc/examples/njs/README.md
+++ b/doc/examples/njs/README.md
@@ -1,5 +1,22 @@
 # print env via NJS
 
+Dockerfile:
+
+```dockerfile
+FROM docker.io/rockdrilla/angie-conv:v0.0.1
+
+COPY /site/ /etc/angie/site/
+
+## install 'angie-module-njs' and process package contents
+RUN apt-install-angie-mod.sh njs ; \
+    apt-clean.sh
+
+## load ngx_http_js_module
+ENV NGX_HTTP_MODULES='njs'
+```
+
+---
+
 configuration:
 
 ```nginx
@@ -16,6 +33,8 @@ server {
 }
 ```
 
+---
+
 NJS script:
 
 ```js
@@ -33,20 +52,7 @@ function report(r) {
 export default { report };
 ```
 
-Dockerfile:
-
-```dockerfile
-FROM docker.io/rockdrilla/angie-conv:v0.0.1
-
-COPY /site/ /etc/angie/site/
-
-## install 'angie-module-njs' and process package contents
-RUN apt-install-angie-mod.sh njs ; \
-    apt-clean.sh
-
-## load ngx_http_js_module
-ENV NGX_HTTP_MODULES='njs'
-```
+---
 
 Test URI e.g. with `curl`:
 ```sh
diff --git a/doc/examples/perl/README.md b/doc/examples/perl/README.md
index 2c83251..332264e 100644
--- a/doc/examples/perl/README.md
+++ b/doc/examples/perl/README.md
@@ -1,5 +1,22 @@
 # print env via Perl
 
+Dockerfile:
+
+```dockerfile
+FROM docker.io/rockdrilla/angie-conv:v0.0.1
+
+COPY /site/ /etc/angie/site/
+
+## install 'angie-module-perl' and process package contents
+RUN apt-install-angie-mod.sh perl ; \
+    apt-clean.sh
+
+## load ngx_http_perl_module
+ENV NGX_HTTP_MODULES='perl'
+```
+
+---
+
 configuration:
 
 ```nginx
@@ -16,6 +33,8 @@ server {
 }
 ```
 
+---
+
 Perl script:
 
 ```perl
@@ -43,20 +62,7 @@ sub report {
 __END__
 ```
 
-Dockerfile:
-
-```dockerfile
-FROM docker.io/rockdrilla/angie-conv:v0.0.1
-
-COPY /site/ /etc/angie/site/
-
-## install 'angie-module-perl' and process package contents
-RUN apt-install-angie-mod.sh perl ; \
-    apt-clean.sh
-
-## load ngx_http_perl_module
-ENV NGX_HTTP_MODULES='perl'
-```
+---
 
 Test URI e.g. with `curl`:
 ```sh
diff --git a/doc/examples/ssl/README.md b/doc/examples/ssl/README.md
index 728b564..d039028 100644
--- a/doc/examples/ssl/README.md
+++ b/doc/examples/ssl/README.md
@@ -1,20 +1,5 @@
 # SSL with subdomains
 
-configuration:
-
-```nginx
-server {
-    listen 8443 ssl;
-
-    server_name example.org;
-
-    ssl_certificate      tls.d/example.org.chain.crt;
-    ssl_certificate_key  tls.d/example.org.pem;
-
-    root static.d/example.org;
-}
-```
-
 Dockerfile:
 
 ```dockerfile
@@ -27,7 +12,45 @@ COPY /tls/    /etc/angie/tls/
 ENV NGX_HTTP_CONFLOAD='ssl'
 ```
 
-Optional cut-off SSL server block:
+---
+
+configuration:
+
+```nginx
+server {
+    listen 8443 ssl;
+
+    server_name www.example.org;
+
+    ssl_certificate      tls.d/www.example.org.chain.crt;
+    ssl_certificate_key  tls.d/www.example.org.pem;
+
+    root static.d/www.example.org;
+}
+```
+
+---
+
+configuration for wildcard certificate:
+
+```nginx
+server {
+    listen 8443 ssl;
+
+    server_name .example.org;
+
+    ssl_certificate      tls.d/example.org.chain.crt;
+    ssl_certificate_key  tls.d/example.org.pem;
+
+    root static.d/example.org;
+}
+```
+
+*Note: certificate must have* `X509v3 Subject Alternative Name` *property with value like* `DNS:example.org, DNS:*.example.org` .
+
+---
+
+(optional) configuration for cut-off SSL server block (see [documentation](https://angie.software/en/configuration/modules/http/http_ssl/#ssl-reject-handshake) for rationale):
 
 ```nginx
 server {
@@ -42,6 +65,8 @@ server {
 }
 ```
 
+---
+
 Test URI e.g. with `curl`:
 ```sh
 curl --cacert ./tls/ca/root-ca.crt --capath /nonexistent --resolve example.org:8443:127.0.0.1 https://example.org:8443/