From 8d0b76f4592be0708af3cea57eb3cf193f5a3169 Mon Sep 17 00:00:00 2001
From: "Hahn Axel (hahn)" <axel.hahn@unibe.ch>
Date: Wed, 8 Jan 2025 12:04:58 +0100
Subject: [PATCH] update docs
---
docs/30_Usage.md | 137 +++++++++++++++++++++++-----------------
docs/style.css | 161 +++++++++++++++++++++++++++++++++--------------
2 files changed, 193 insertions(+), 105 deletions(-)
diff --git a/docs/30_Usage.md b/docs/30_Usage.md
index e998df7..f172c21 100644
--- a/docs/30_Usage.md
+++ b/docs/30_Usage.md
@@ -6,94 +6,113 @@ Verify a new setup (or changes in the config) with `./cm.sh selftest`.
## Show help
-Without any parameter it shows a help.
+Without -h or --help it shows a help.
```text
-./cm.sh
+./cm.sh -h
_______________________________________________________________________________
- - - - ---===>>> CERT MANAGER <<<===--- - - -
+ - - - ---===>>> CERT MANAGER - v2025-01-08 <<<===--- - - -
_______________________________________________________________________________
-DEBUG: Using Let's Encrypt STAGE environment ...
-DEBUG: You can test and mess around. Do not use certs in production.
-
HELP
-The basic syntax is
-cm.sh [--trace] ACTION [FQDN] [ALIAS_1 [.. ALIAS_N]]
+Wrapper script for acme.sh to handle certificates.
+For automation you should use the "ensure" action that detects if a
+certificate must be created, renewed or re-created.
-The ACTIONs for SINGLE certificate handlings are:
+📄 Source: <https://git-repo.iml.unibe.ch/iml-open-source/iml-certman>
+📜 License: GNU GPL 3.0
+📗 Docs: <https://os-docs.iml.unibe.ch/iml-certman/>
- add FQDN [.. FQDN-N]
- create new certificate
- The first FQDN is a hostname to generate the certificate for.
- Following multiple hostnames will be used as DNS aliases in the
- same certificate.
- It updates files in ./certs
+SYNTAX:
- ensure FQDN [.. FQDN-N]
- It ensures that a certificate with given aliases exists and is up to date.
- This param is for simple usage in automation tools like Ansible or Puppet.
- It is required to add all aliases as parameters what is unhandy for
- direct usage on cli.
+ dev_cm.sh [OPTIONS] ACTION <FQDN> [<ALIASES>]
- If the cert does not exist it will be created (see "add").
- If fqdn and aliases are the same like in the certificate it performs a renew.
- If fqdn and aliases differ:
- - the current certificate will be rejected + deleted (see "delete")
- - a new certificate will be added ()
+OPTIONS:
- delete FQDN
- delete all files of a given certificate
+ -a|--alias
+ Use http challenge with existing http server on port 80
+ Challenge file will be written into ../alias-dir/
- renew FQDN
- renew (an already added) certificate
- and update files in ./certs
+ -f|--force
+ Force renew of certificate even if it is not due yet.
+ Use it carefully - remember the execution limits on Let's Encrypt.
- show FQDN
- show place of certificate data and show basic certificate data
- (issuer, subject, aliases, ending date)
+ -t|--trace
+ the output additionally will be written into a tracelog file
+ below ./log.
- transfer FQDN
- Transfer cert from acme.sh internal cache to our output dir again.
- It is done during add or renew. With transfer command you can repeat it.
+ -v|--verbose
+ show debug infos on console.
+ Remark: for permanent usage set CM_showdebug=1 in inc_config.sh
-ACTIONs for ALL certs
+ -w|--webroot <DIR>
+ Use http challenge with existing http server on port 80
+ Challenge file will be written into given directory
- list
- list all certificates including creation and renew date
+The ACTIONs for SINGLE certificate handlings are:
- list-old
- list all certificates older 65 and older 90 days and exit.
- Exitcodes:
- 0 - all certs are up to date.
- 1 - certificates to renew were found
- 2 - outdatedt certificates were found
+ add <FQDN> [.. <FQDN-N>]
+ create new certificate
+ The first FQDN is a hostname to generate the certificate for.
+ Following multiple hostnames will be used as DNS aliases in the
+ same certificate.
+ It updates files in
- renew-all
- renew all certificates (fast mode - without --force)
- and update files in ./certs
- It is useful for a cronjob.
+ ensure <FQDN> [.. <FQDN-N>]
+ It ensures that a certificate with given aliases exists and is up to date.
+ This param is for simple usage in automation tools like Ansible or Puppet.
+ It is required to add all aliases as parameters what is unhandy for
+ direct usage on cli.
-other ACTIONs
+ If the cert does not exist it will be created (see "add").
+ If fqdn and aliases are the same like in the certificate it performs a renew.
+ If fqdn and aliases differ:
+ - the current certificate will be rejected + deleted (see "delete")
+ - a new certificate will be added ()
+
+ delete <FQDN>
+ delete all files of a given certificate
+
+ renew <FQDN>
+ renew (an already added) certificate
+ and update files in
- selftest
- check of health with current setup and requirements.
- This command is helpful for initial setups.
+ show <FQDN>
+ show place of certificate data and show basic certificate data
+ (issuer, subject, aliases, ending date)
-OPTIONS
- --trace (it must be the 1st parameter)
- the output additionally will be written into a tracelog file
- below ./log.
+ transfer <FQDN>
+ Transfer cert from acme.sh internal cache to our output dir again.
+ It is done during add or renew. With transfer command you can repeat it.
+ACTIONs for ALL certs
+
+ list
+ list all certificates including creation and renew date
+
+ list-old
+ list all certificates older 65 and older 90 days and exit.
+ Exitcodes:
+ 0 - all certs are up to date.
+ 1 - certificates to renew were found
+ 2 - outdatedt certificates were found
+
+ renew-all
+ renew all certificates (fast mode - without --force)
+ and update files in
+ It is useful for a cronjob.
+
+other ACTIONs
-DEBUG: Using Let's Encrypt STAGE environment ...
-DEBUG: You can test and mess around. Do not use certs in production.
+ selftest
+ check of health with current setup and requirements.
+ This command is helpful for initial setups.
```
diff --git a/docs/style.css b/docs/style.css
index 18463c7..90a0bc9 100644
--- a/docs/style.css
+++ b/docs/style.css
@@ -1,52 +1,59 @@
/*
override css elements of daux.io blue theme
- version 2022-11-30
+ version 2024-10-31
*/
:root {
/* Axels Overrides */
- --color-text: #222;
- --link-color: #822;
- --brand-color: var(--color-secondary);
+ --color-text: #234;
+ --link-color: #228;
+ --brand-color: var(--color-text);
--brand-background: var(--body-background);
+ --code-tag-background-color: #f0f3f3;
+ --code-tag-border-color: #dee;
+ --code-tag-box-shadow: none;
--hr-color: none;
+ --pager-background-color: #f8fafa;
+ --pager-border-color: none;
--search-field-background: none;
--search-field-border-color: none;
--sidebar-background: var(--body-background);
--sidebar-border-color: none;
- --sidebar-link-active-background: #e8f4f6;
- --sidebar-link-active-background: #eee;
+ --sidebar-link-active-background: #f0f4f6;
+ --toc--inner-border-color: none;
/* Axels custom values */
- --axel_bg-toc: var(--body-background);
+ --axel_bg-toc: #f8fafa;
--axel_bg-toc-head: #f8f8f8;
--axel_brand-background: none;
--axel_brand-pre-background: rgb(255, 0, 51);
- ;
--axel_brand-pre-background-hover: rgb(255, 0, 51);
- ;
--axel_h1_header: none;
- --axel_h1: #345;
+ --axel_h1: #111;
--axel_h1-bg: none;
--axel_h1-bottom: 3px solid none;
- --axel_h2: #156;
- --axel_h2-bg: #f8fafb;
- --axel_h2-bottom: 2px solid #467;
+ --axel_h2: #222;
+ --axel_h2-bg: none;
+ --axel_h2-bottom: 0px solid #467;
--axel_h2-hero-bottom: 2px solid #912;
- --axel_h3: #278;
- --axel_h3-bottom: 1px solid #ddd;
- --axel_hero_bg: #f8f8f8;
+ --axel_h3: #333;
+ --axel_h3-bottom: 0px solid #ddd;
+ --axel_h4: #666;
+ --axel_h5: #888;
+ --axel_hero_bg: #faf8f6;
+ --axel_img-border: 2px dashed #ccc;
--axel_nav-bg: #fcfcfc;
--axel_nav-buttomborder: #ddd;
- --axel_pre-background: #f8f8f8;
- --axel-th-background: #d0e0e8;
+ --axel_pre-background: #faf8f6;
+ --axel-th-background: #e0e4e8;
--axel-article-nav-border-top: 0px dotted #ddd;
}
.dark {
/* Axels Overrides */
--color-text: #c0c0c0;
- --link-color: #b44;
+ --link-color: #88e;
--brand-color: var(--color-text);
--brand-background: var(--body-background);
+ --body-background: #101418;
--hr-color: none;
--code-tag-background-color_: #bcc;
--search-field-background: none;
@@ -54,6 +61,7 @@
--sidebar-background: var(--body-background);
--sidebar-border-color: none;
--sidebar-link-active-background: #333;
+ --sidebar-link-color: var(--link-color);
/* Axels custom values */
--axel_bg-toc: var(--body-background);
--axel_bg-toc-head: #333;
@@ -63,16 +71,19 @@
--axel_brand-pre-background-hover: rgb(255, 0, 51);
;
--axel_h1_header: none;
- --axel_h1: #777;
+ --axel_h1: #578;
--axel_h1-bg: none;
--axel_h1-bottom: none;
--axel_h2: #467;
- --axel_h2-bg: #202020;
- --axel_h2-bottom: 2px solid #256;
+ --axel_h2-bg: none;
+ --axel_h2-bottom: 0px solid #256;
--axel_h2-hero-bottom: 2px solid #712;
--axel_h3: #589;
- --axel_h3-bottom: 1px solid #333;
+ --axel_h3-bottom: 0px solid #333;
+ --axel_h4: #478;
+ --axel_h5: #278;
--axel_hero_bg: #242424;
+ --axel_img-border: 2px dashed #555;
--axel_nav-bg: #242424;
--axel_nav-buttomborder: #555;
--axel_pre-background: #bcc;
@@ -117,7 +128,25 @@ a.Brand {
/* ---------- page content ---------- */
.s-content {
- padding-top: 1em;
+ padding-top: 6em;
+}
+
+/**
+h1::before{color: #aaa;content: 'h1: ';}
+h2::before{color: #aaa;content: 'h2: ';}
+h3::before{color: #aaa;content: 'h3: ';}
+h4::before{color: #aaa;content: 'h4: ';}
+h5::before{color: #aaa;content: 'h5: ';}
+h6::before{color: #aaa;content: 'h6: ';}
+*/
+h2::before{color: #888;content: ': : ';}
+h3::before{color: #ccc;content: '> ';}
+h4::before{color: #ccc;content: '_ ';}
+
+.s-content h1::before{
+ color: #f00;
+ content: 'FEHLER: Keine Überschrift 1 in einer Markdown-Datei für Daux verwenden! Mit H2 beginnen!';
+ content: '!! h1 !! ';
}
.s-content h1 {
@@ -133,20 +162,32 @@ a.Brand {
.s-content h2 {
background: var(--axel_h2-bg);
color: var(--axel_h2);
- font-size: 180%;
+ font-size: 190%;
font-weight: bold;
margin-top: 4em;
border-bottom: var(--axel_h2-bottom);
}
-h1:first-of-type {
+.Page__header > h1:first-of-type {
margin-top: 0em;
+ margin-left: -1em;
+ padding-left: 1em;
+ position: fixed;
+ min-width: 100%;
+ background: var(--body-background);
+ box-shadow: 0 2em 1em var(--body-background);
}
h2:first-of-type {
margin-top: 0em;
}
+img{
+ border: var(--axel_img-border);
+ border-radius: 1.5em;
+ padding: 0.7em;
+}
+
.s-content h3 {
background: var(--axel_h3-bg);
color: var(--axel_h3);
@@ -156,16 +197,37 @@ h2:first-of-type {
border-bottom: var(--axel_h3-bottom);
}
-.s-content h4 {
- margin: 0;
- font-size: 100%;
+
+.s-content > h4 {
+ color: var(--axel_h4);
+ font-size: 140%;
+ font-weight: bold;
+ margin: 2em 0;
+}
+
+.s-content > h5 {
+ color: var(--axel_h5);
+ font-size: 135%;
+ font-weight: bold;
+ margin: 2em 0;
+}
+
+.s-content .TableOfContentsContainer h4 {
+ margin: 1em 0;
+ font-size: 110%;
text-align: center;
- background-color: rgba(0, 0, 0, 0.05);
+ background-color: rgba(0, 0, 0, 0.1);
padding: 0.3em;
+ font-weight: bold;
+ font-family: Arial;
+}
+ul.TableOfContents a{
+ color: var(--color-text);
}
-
.s-content pre {
background: var(--axel_pre-background);
+ border-radius: 0.5em;
+ padding: 1rem;
}
/* FIX smaller fnt size in tables */
@@ -217,13 +279,6 @@ div.hero h2 {
}
/* ---------- TOC ---------- */
-@media(min-width:1700px) {
- .TableOfContentsContainer {
- position: fixed;
- right: 2em;
- top: 1em;
- }
-}
.TableOfContentsContainer {
background-color: var(--axel_bg-toc);
@@ -233,14 +288,18 @@ div.hero h2 {
.s-content .TableOfContentsContainer h4 {
background-color: var(--axel_bg-toc-head);
border-top-left-radius: 1em;
+ border-bottom: 2px solid var(--axel_bg-toc-bottom-border);
font-size: 1.1em;
margin: 0;
- padding: 0;
+ padding: 0.3em;
+ display: none;
}
.TableOfContentsContainer__content {
- border-width: 1px;
+ border-width: 0px;
font-size: 0.5em;
+ height: inherit;
+ overflow: auto;
}
ul.TableOfContents ul {
@@ -248,20 +307,30 @@ ul.TableOfContents ul {
padding-left: 1em;
}
+.TableOfContents a:hover{
+ text-decoration: underline;
+}
+
+@media(min-width:1700px) {
+ .TableOfContentsContainer {
+ background: none;
+ position: fixed;
+ right: 2em;
+ top: 4em;
+ height: 90%;
+ }
+}
+
/* ----- Icons on links --- */
.EditOn a::before{
content: 'âœï¸ ';
}
-.Links a[href^="https://github.com/"]::before {
- content: '🌠';
-}
-
-.Links a[href^="https://git-repo.iml.unibe.ch/"]::before {
+.Links a::before {
content: '🌠';
}
.Links a[href^="https://os-docs.iml.unibe.ch"]::before {
content: '📗 ';
-}
\ No newline at end of file
+}
--
GitLab