From eaddb57c274d9d9b8a78bf40055007e437bcd541 Mon Sep 17 00:00:00 2001 From: James Elliott Date: Mon, 1 May 2023 12:36:02 +1000 Subject: [PATCH] docs: add exhaustive complete logs reference guide (#5345) Signed-off-by: James Elliott --- .github/ISSUE_TEMPLATE/bug-report.yml | 9 +- cmd/authelia-gen/cmd_docs_date.go | 14 ++- .../github_issue_template_bug_report.yml.tmpl | 9 +- cmd/authelia-scripts/cmd/gen.go | 2 +- .../contributing/guidelines/commit-message.md | 4 +- .../openid-connect/kasm-workspaces/index.md | 2 +- .../en/reference/guides/http-archive-file.md | 2 +- .../guides/troubleshooting-sanitizaiton.md | 42 -------- .../en/reference/guides/troubleshooting.md | 99 +++++++++++++++++++ 9 files changed, 130 insertions(+), 53 deletions(-) delete mode 100644 docs/content/en/reference/guides/troubleshooting-sanitizaiton.md create mode 100644 docs/content/en/reference/guides/troubleshooting.md diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml index 6794b8e78..10fda1cca 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.yml +++ b/.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 diff --git a/cmd/authelia-gen/cmd_docs_date.go b/cmd/authelia-gen/cmd_docs_date.go index fb2883492..a51876ded 100644 --- a/cmd/authelia-gen/cmd_docs_date.go +++ b/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) diff --git a/cmd/authelia-gen/templates/github_issue_template_bug_report.yml.tmpl b/cmd/authelia-gen/templates/github_issue_template_bug_report.yml.tmpl index 04349e6ba..c15625ca4 100644 --- a/cmd/authelia-gen/templates/github_issue_template_bug_report.yml.tmpl +++ b/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 diff --git a/cmd/authelia-scripts/cmd/gen.go b/cmd/authelia-scripts/cmd/gen.go index b2774c261..be6a36a9e 100644 --- a/cmd/authelia-scripts/cmd/gen.go +++ b/cmd/authelia-scripts/cmd/gen.go @@ -7,5 +7,5 @@ package cmd const ( - versionSwaggerUI = "4.18.2" + versionSwaggerUI = "4.18.3" ) diff --git a/docs/content/en/contributing/guidelines/commit-message.md b/docs/content/en/contributing/guidelines/commit-message.md index 7ab32ba15..2d84ed186 100644 --- a/docs/content/en/contributing/guidelines/commit-message.md +++ b/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` -- To correct a single commit missing the sign off `git commit –-amend --signoff --no-edit` +- While making the commit use `git commit --signoff` or `git commit -s` +- 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 diff --git a/docs/content/en/integration/openid-connect/kasm-workspaces/index.md b/docs/content/en/integration/openid-connect/kasm-workspaces/index.md index 30bd8d7cb..2860bcbf1 100644 --- a/docs/content/en/integration/openid-connect/kasm-workspaces/index.md +++ b/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: diff --git a/docs/content/en/reference/guides/http-archive-file.md b/docs/content/en/reference/guides/http-archive-file.md index ff18947e5..1d2c715e0 100644 --- a/docs/content/en/reference/guides/http-archive-file.md +++ b/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 diff --git a/docs/content/en/reference/guides/troubleshooting-sanitizaiton.md b/docs/content/en/reference/guides/troubleshooting-sanitizaiton.md deleted file mode 100644 index 46448ada6..000000000 --- a/docs/content/en/reference/guides/troubleshooting-sanitizaiton.md +++ /dev/null @@ -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 diff --git a/docs/content/en/reference/guides/troubleshooting.md b/docs/content/en/reference/guides/troubleshooting.md new file mode 100644 index 000000000..96f0b07d9 --- /dev/null +++ b/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.