docs: add exhaustive complete logs reference guide (#5345)

Signed-off-by: James Elliott <james-d-elliott@users.noreply.github.com>

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -17,7 +17,9 @@ body:
         2. Please try to give as much information as possible for us to be able to reproduce the issue and provide a quick fix.
         3. Please ensure an issue does not already exist for this potential bug.
         4. Please only provide specific versions. Latest is not a version.
-        5. Please read the [Troubleshooting Sanitization](https://www.authelia.com/r/sanitize) reference guide if you plan on sanitizing, removing, or adjusting any values for the logs or configuration files.
+        5. Please read the [Troubleshooting](https://www.authelia.com/r/troubleshooting) reference guide:
+          - Do not truncate any logs unless you are complying with the specific instructions in the [Logs](https://www.authelia.com/r/troubleshooting#logs) section.
+          - If you plan on sanitizing, removing, or adjusting any values for the logs or configuration files please read the [Sanitization](https://www.authelia.com/r/troubleshooting#sanitization) section.
         6. Please consider including a [HTTP Archive File](https://www.authelia.com/r/har) if you're having redirection issues.
   - type: dropdown
     id: version
@@ -135,7 +137,10 @@ body:
       label: Logs (Authelia)
       description: |
         Provide complete logs with the log level set to debug or trace. Complete means from application start until the
-        issue occurring. The template will automatically put this content in a code block so you can just paste it.
+        issue occurring. This is clearly explained in the [Logs](https://www.authelia.com/r/troubleshooting#logs)
+        section of the troubleshooting guide.
+
+        The template will automatically put this content in a code block so you can just paste it.
       render: shell
     validations:
       required: true

cmd/authelia-gen/cmd_docs_date.go

@@ -13,7 +13,7 @@ import (
 
 	"github.com/spf13/cobra"
 	"github.com/valyala/fasthttp"
-	"gopkg.in/yaml.v3"
+	yaml "gopkg.in/yaml.v3"
 )
 
 func newDocsDateCmd() *cobra.Command {
@@ -87,7 +87,17 @@ func docsDateRunE(cmd *cobra.Command, args []string) (err error) {
 		)
 
 		if value, ok := frontmatter["date"]; ok {
-			date = value.(time.Time)
+			date, ok = value.(time.Time)
+
+			if !ok {
+				var abspath string
+
+				if abspath, err = filepath.Abs(path); err != nil {
+					abspath = path
+				}
+
+				return fmt.Errorf("frontmatter for %s has an invalid date value: is %T with a value of %s", abspath, value, value)
+			}
 		}
 
 		dateGit := getDateFromGit(cwd, abs, commitFilter)

cmd/authelia-gen/templates/github_issue_template_bug_report.yml.tmpl

@@ -17,7 +17,9 @@ body:
         2. Please try to give as much information as possible for us to be able to reproduce the issue and provide a quick fix.
         3. Please ensure an issue does not already exist for this potential bug.
         4. Please only provide specific versions. Latest is not a version.
-        5. Please read the [Troubleshooting Sanitization](https://www.authelia.com/r/sanitize) reference guide if you plan on sanitizing, removing, or adjusting any values for the logs or configuration files.
+        5. Please read the [Troubleshooting](https://www.authelia.com/r/troubleshooting) reference guide:
+          - Do not truncate any logs unless you are complying with the specific instructions in the [Logs](https://www.authelia.com/r/troubleshooting#logs) section.
+          - If you plan on sanitizing, removing, or adjusting any values for the logs or configuration files please read the [Sanitization](https://www.authelia.com/r/troubleshooting#sanitization) section.
         6. Please consider including a [HTTP Archive File](https://www.authelia.com/r/har) if you're having redirection issues.
   - type: dropdown
     id: version
@@ -97,7 +99,10 @@ body:
       label: Logs (Authelia)
       description: |
         Provide complete logs with the log level set to debug or trace. Complete means from application start until the
-        issue occurring. The template will automatically put this content in a code block so you can just paste it.
+        issue occurring. This is clearly explained in the [Logs](https://www.authelia.com/r/troubleshooting#logs)
+        section of the troubleshooting guide.
+
+        The template will automatically put this content in a code block so you can just paste it.
       render: shell
     validations:
       required: true

cmd/authelia-scripts/cmd/gen.go

@@ -7,5 +7,5 @@
 package cmd
 
 const (
-	versionSwaggerUI = "4.18.2"
+	versionSwaggerUI = "4.18.3"
 )

docs/content/en/contributing/guidelines/commit-message.md

@@ -182,8 +182,8 @@ By making a contribution to this project, I certify that:
 
 This can be achieved in the following ways:
 
-- While making the commit use `git commit --signoff`
+- While making the commit use `git commit --signoff` or `git commit -s`
-- To correct a single commit missing the sign off `git commit –-amend --signoff --no-edit`
+- To correct a single commit missing the sign off `git commit –-amend --no-edit --signoff` or `git commit --amend --no-edit -s`
 - To correct multiple commits missing the sign off `git rebase --signoff HEAD~2` (i.e. with 2 commits that are missing the sign off)
 
 This can be achieved by using `git commit --signoff`. A single previous commit can be signed using

docs/content/en/integration/openid-connect/kasm-workspaces/index.md

@@ -2,7 +2,7 @@
 title: "Kasm Workspaces"
 description: "Integrating Kasm Workspaces with the Authelia OpenID Connect Provider."
 lead: ""
-date: 2023-04-25T23:07:05+2:00
+date: 2023-04-27T18:40:06+10:00
 draft: false
 images: []
 menu:

docs/content/en/reference/guides/http-archive-file.md

@@ -29,7 +29,7 @@ present in an environment.
 
 The following section outlines some helpful information if you wish to sanitize your HAR file to share it with others.
 
-For generic sanitization information see the [Troubleshooting Sanitization guide](troubleshooting-sanitizaiton.md).
+For generic sanitization information see the [Troubleshooting Sanitization guide](troubleshooting.md#sanitization).
 
 ### Security Sensitive Information
 

docs/content/en/reference/guides/troubleshooting-sanitizaiton.md

@@ -1,42 +0,0 @@
----
-title: "Troubleshooting Sanitization"
-description: "This guide describes and helps users sanitize provided files to hide privacy related values for troubleshooting"
-lead: "This guide describes and helps users sanitize provided files to hide information for privacy."
-date: 2022-09-16T14:21:05+10:00
-draft: false
-images: []
-menu:
-  reference:
-    parent: "guides"
-weight: 220
-toc: true
-aliases:
-  - /r/sanitize
----
-
-Some users may wish to hide their domain in files provided during troubleshooting. While this is discouraged, if a user
-decides to perform this action it's critical for these purposes that you hide your domain in a very specific
-way. Most editors allow replacing all instances of a value, utilizing this is essential to making troubleshooting
-possible.
-
-## General Rules
-
-1. Only replace the purchased portion of domains:
-   - For example if you have `auth.abc123.com` and `app.abc123.com` they
-   should become `auth.example.com` and `app.example.com`, i.e. replace all instances of `abc123.com` with `example.com`.
-2. Make sure value replaced is replaced with a unique value:
-   - For example if you replace `abc123.com` with `example.com` DO NOT replace any other value other than `abc123.com` with
-   `example.com`. The same rule applies to IP addresses, usernames, and groups.
-3. Make sure the value replaced is replaced across logs, configuration, and any references:
-   - For example if you replace `abc123.com` with `example.com` in your configuration, make exactly the same replacement
-   for the log files.
-4. Make sure this consistency is followed for all communication regarding a single issue.
-
-## Multiple Domains
-
-*__Replacement Value:__* `example#.com` (where `#` is a unique number per domain)
-
-In instances where there are multiple domains it's recommended these domains are replaced with `example1.com`,
-`example2.com`, etc.
-
-## Specific Values

docs/content/en/reference/guides/troubleshooting.md

@@ -0,0 +1,99 @@
+---
+title: "Troubleshooting"
+description: "This guide describes and helps users provide information during troubleshooting including sanitization etc"
+lead: "This guide describes and helps users provide troubleshooting information."
+date: 2023-05-01T11:30:07+10:00
+draft: false
+images: []
+menu:
+  reference:
+    parent: "guides"
+weight: 220
+toc: true
+aliases:
+  - /r/sanitize
+  - /r/troubleshoot
+  - /r/troubleshooting
+---
+
+## Frequently Asked Questions
+
+See the [Frequently Asked Questions](frequently-asked-questions.md) reference guide for links to frequently asked
+question documentation.
+
+## Logs
+
+It's really important when troubleshooting and even more important when reporting a bug that users provide complete
+log files. In addition the [log level](../../configuration/miscellaneous/logging.md#level) should always be set to
+`debug` at minimum, if not `trace`.
+
+Complete logs means at minimum from the [log severity line](#log-severity-line) until the actual issue occurs. Though
+more than this may be included at the users discretion.
+
+### Large Amount of Logs
+
+In instances where the logs are substantial we will accept truncated logs. There are however some very intentional rules
+about truncation of logs.
+
+1. You must show more than 1 minute of logs prior to the issue occurring (i.e. show every log line )
+2. The level rule still applies.
+3. You must show:
+   1. The [log severity line](#log-severity-line).
+   2. The [listening line](#listening-line) and the 10 log lines which follow this line.
+   3. The lines between these two lines, which should also include the [starting line](#starting-line).
+4. No warning or error that is potentially related to the issue should be truncated.
+
+### Important Log Lines
+
+The following log lines are important and are referenced by other sections of this document.
+
+#### Log Severity Line
+
+The log severity line will have a message which is similar to the following examples:
+
+- `Log severity set to debug`
+- `Log severity set to trace`
+
+#### Starting Line
+
+The starting line will have a message which is similar to the following examples:
+
+- `Authelia v4.37.5 is starting`
+- `Authelia v4.38.0 is starting`
+- `Authelia untagged-v4.38.0 (master, 50d8b4a) is starting`
+
+#### Listening Line
+
+The listening line will have a message which is similar to the following examples:
+
+- `Listening for non-TLS connections on '0.0.0.0:9091' path '/'`
+- `Listening for TLS connections on '0.0.0.0:9091' path '/'`
+- `Listening for non-TLS connections on ':9091' path '/'`
+- `Listening for non-TLS connections on ':9091' path '/' and '/authelia'`
+
+## Sanitization
+
+Some users may wish to hide their domain in files provided during troubleshooting. While this is discouraged, if a user
+decides to perform this action it's critical for these purposes that you hide your domain in a very specific
+way. Most editors allow replacing all instances of a value, utilizing this is essential to making troubleshooting
+possible.
+
+### General Rules
+
+1. Only replace the purchased portion of domains:
+   - For example if you have `auth.abc123.com` and `app.abc123.com` they
+   should become `auth.example.com` and `app.example.com`, i.e. replace all instances of `abc123.com` with `example.com`.
+2. Make sure value replaced is replaced with a unique value:
+   - For example if you replace `abc123.com` with `example.com` DO NOT replace any other value other than `abc123.com` with
+   `example.com`. The same rule applies to IP addresses, usernames, and groups.
+3. Make sure the value replaced is replaced across logs, configuration, and any references:
+   - For example if you replace `abc123.com` with `example.com` in your configuration, make exactly the same replacement
+   for the log files.
+4. Make sure this consistency is followed for all communication regarding a single issue.
+
+### Multiple Domains
+
+*__Replacement Value:__* `example#.com` (where `#` is a unique number per domain)
+
+In instances where there are multiple domains it's recommended these domains are replaced with `example1.com`,
+`example2.com`, etc.