refactor(configuration): use key log instead of logging (#2072)

* refactor: logging config key to log

This refactors the recent pre-release change adding log options to their own configuration section in favor of a log section (from logging).

* docs: add step to getting started to get the latest tagged commit

This is so we avoid issues with changes on master having differences that don't work on the latest docker tag.

* test: adjust tests

* docs: adjust doc strings

config.template.yml

@@ -30,6 +30,7 @@ server:
   ## Write buffer size does the same for outgoing responses.
   read_buffer_size: 4096
   write_buffer_size: 4096
+
   ## Set the single level path Authelia listens on.
   ## Must be alphanumeric chars and should not contain any slashes.
   path: ""
@@ -40,8 +41,8 @@ server:
   ## Enables the expvars endpoint.
   enable_expvars: false
 
-## Level of verbosity for logs: info, debug, trace.
-logging:
+log:
+  ## Level of verbosity for logs: info, debug, trace.
   level: debug
 
   ## Format the logs are written as: json, text.

docs/configuration/logging.md

@@ -12,7 +12,7 @@ The logging section tunes the logging settings.
 ## Configuration
 
 ```yaml
-logging:
+log:
   level: info
   format: text
   file_path: ""
@@ -36,7 +36,7 @@ setting level to `trace`, you will generate a large amount of log entries and ex
 `/debug/pprof/` endpoints which should not be enabled in production.
 
 ```yaml
-logging:
+log:
   level: debug
 ```
 
@@ -53,7 +53,7 @@ required: no
 Defines the format of the logs written by Authelia. This format can be set to `json` or `text`.
 
 ```yaml
-logging:
+log:
   format: json
 ```
 
@@ -83,7 +83,7 @@ level to `debug` or `trace` this will generate large amount of log entries. Admi
 they rotate and/or truncate the logs over time to prevent significant long-term disk usage.
 
 ```yaml
-logging:
+log:
   file_path: /config/authelia.log
 ```
 
@@ -101,6 +101,6 @@ Overrides the behaviour to redirect logging only to the `file_path`. If set to `
 standard output, and the defined logging location.
 
 ```yaml
-logging:
+log:
   keep_stdout: true
 ```

docs/getting-started.md

@@ -14,6 +14,7 @@ These commands are intended to be run sequentially:
 
 - `git clone https://github.com/authelia/authelia.git`
 - `cd authelia/examples/compose/local`
+- ``git checkout $(git describe --tags `git rev-list --tags --max-count=1`)``
 - `sudo ./setup.sh` *sudo is required to modify the `/etc/hosts` file*
 
 You can now visit the following locations; replace example.com with the domain you specified in the setup script:

examples/compose/lite/authelia/configuration.yml

@@ -5,7 +5,7 @@
 
 host: 0.0.0.0
 port: 9091
-logging:
+log:
   level: debug
 # This secret can also be set using the env variables AUTHELIA_JWT_SECRET_FILE
 jwt_secret: a_very_important_secret

examples/compose/local/authelia/configuration.yml

@@ -5,7 +5,7 @@
 
 host: 0.0.0.0
 port: 9091
-logging:
+log:
   level: debug
 jwt_secret: a_very_important_secret
 default_redirection_url: https://public.example.com

internal/configuration/config.template.yml

@@ -30,6 +30,7 @@ server:
   ## Write buffer size does the same for outgoing responses.
   read_buffer_size: 4096
   write_buffer_size: 4096
+
   ## Set the single level path Authelia listens on.
   ## Must be alphanumeric chars and should not contain any slashes.
   path: ""
@@ -40,8 +41,8 @@ server:
   ## Enables the expvars endpoint.
   enable_expvars: false
 
-## Level of verbosity for logs: info, debug, trace.
-logging:
+log:
+  ## Level of verbosity for logs: info, debug, trace.
   level: debug
 
   ## Format the logs are written as: json, text.

internal/configuration/reader_test.go

@@ -164,7 +164,7 @@ func TestShouldErrorParseBadConfigFile(t *testing.T) {
 
 	require.Len(t, errors, 1)
 
-	require.EqualError(t, errors[0], "Error malformed yaml: line 25: did not find expected alphabetic or numeric character")
+	require.EqualError(t, errors[0], "Error malformed yaml: line 26: did not find expected alphabetic or numeric character")
 }
 
 func TestShouldParseConfigFile(t *testing.T) {
@@ -253,7 +253,7 @@ func TestShouldNotParseConfigFileWithOldOrUnexpectedKeys(t *testing.T) {
 		return errors[i].Error() < errors[j].Error()
 	})
 	assert.EqualError(t, errors[0], "config key not expected: loggy_file")
-	assert.EqualError(t, errors[1], "invalid configuration key 'logs_level' was replaced by 'logging.level'")
+	assert.EqualError(t, errors[1], "invalid configuration key 'logs_level' was replaced by 'log.level'")
 }
 
 func TestShouldValidateConfigurationTemplate(t *testing.T) {

internal/configuration/schema/configuration.go

@@ -17,7 +17,7 @@ type Configuration struct {
 	LogFilePath string `mapstructure:"log_file_path"`
 	// TODO: DEPRECATED END. Remove in 4.33.0.
 
-	Logging               LoggingConfiguration               `mapstructure:"logging"`
+	Logging               LogConfiguration                   `mapstructure:"log"`
 	IdentityProviders     IdentityProvidersConfiguration     `mapstructure:"identity_providers"`
 	AuthenticationBackend AuthenticationBackendConfiguration `mapstructure:"authentication_backend"`
 	Session               SessionConfiguration               `mapstructure:"session"`

internal/configuration/schema/logging.go

@@ -1,7 +1,7 @@
 package schema
 
-// LoggingConfiguration represents the logging configuration.
-type LoggingConfiguration struct {
+// LogConfiguration represents the logging configuration.
+type LogConfiguration struct {
 	Level      string `mapstructure:"level"`
 	Format     string `mapstructure:"format"`
 	FilePath   string `mapstructure:"file_path"`
@@ -9,7 +9,7 @@ type LoggingConfiguration struct {
 }
 
 // DefaultLoggingConfiguration is the default logging configuration.
-var DefaultLoggingConfiguration = LoggingConfiguration{
+var DefaultLoggingConfiguration = LogConfiguration{
 	Level:  "info",
 	Format: "text",
 }

internal/configuration/test_resources/config.yml

@@ -2,8 +2,9 @@
 host: 127.0.0.1
 port: 9091
 
-logging:
+log:
   level: debug
+
 default_redirection_url: https://home.example.com:8080/
 
 totp:

internal/configuration/test_resources/config_alt.yml

@@ -2,8 +2,9 @@
 host: 127.0.0.1
 port: 9091
 
-logging:
+log:
   level: debug
+
 default_redirection_url: https://home.example.com:8080/
 
 totp:

internal/configuration/test_resources/config_bad_keys.yml

@@ -4,6 +4,7 @@ port: 9091
 loggy_file: /config/svc.log
 
 logs_level: debug
+
 default_redirection_url: https://home.example.com:8080/
 
 totp:

internal/configuration/test_resources/config_bad_quoting.yml

@@ -1,7 +1,8 @@
 ---
 host: 0.0.0.0
 port: 9091
-logging:
+
+log:
   level: debug
 
 jwt_secret: RUtG9TnbXrOl1XLLmDgySw1DGgx9QcrtepIf1uDDBlBVKFZxkVBruYKBi32PvaU

internal/configuration/test_resources/config_with_secret.yml

@@ -3,8 +3,9 @@ host: 127.0.0.1
 port: 9091
 jwt_secret: secret_from_config
 
-logging:
+log:
   level: debug
+
 default_redirection_url: https://home.example.com:8080/
 
 totp:

internal/configuration/validator/const.go

@@ -78,11 +78,11 @@ var validKeys = []string{
 	"tls_cert",
 	"certificates_directory",
 
-	// Logging keys.
-	"logging.level",
-	"logging.format",
-	"logging.file_path",
-	"logging.keep_stdout",
+	// Log keys.
+	"log.level",
+	"log.format",
+	"log.file_path",
+	"log.keep_stdout",
 
 	// TODO: DEPRECATED START. Remove in 4.33.0.
 	"log_level",
@@ -217,8 +217,8 @@ var replacedKeys = map[string]string{
 	"authentication_backend.ldap.skip_verify":         "authentication_backend.ldap.tls.skip_verify",
 	"authentication_backend.ldap.minimum_tls_version": "authentication_backend.ldap.tls.minimum_version",
 	"notifier.smtp.disable_verify_cert":               "notifier.smtp.tls.skip_verify",
-	"logs_file_path":                                  "logging.file_path",
-	"logs_level":                                      "logging.level",
+	"logs_file_path":                                  "log.file_path",
+	"logs_level":                                      "log.level",
 }
 
 var specificErrorKeys = map[string]string{

internal/configuration/validator/keys_test.go

@@ -106,8 +106,8 @@ func TestReplacedErrors(t *testing.T) {
 	assert.EqualError(t, errs[0], fmt.Sprintf(errFmtReplacedConfigurationKey, "authentication_backend.ldap.skip_verify", "authentication_backend.ldap.tls.skip_verify"))
 	assert.EqualError(t, errs[1], fmt.Sprintf(errFmtReplacedConfigurationKey, "authentication_backend.ldap.minimum_tls_version", "authentication_backend.ldap.tls.minimum_version"))
 	assert.EqualError(t, errs[2], fmt.Sprintf(errFmtReplacedConfigurationKey, "notifier.smtp.disable_verify_cert", "notifier.smtp.tls.skip_verify"))
-	assert.EqualError(t, errs[3], fmt.Sprintf(errFmtReplacedConfigurationKey, "logs_file_path", "logging.file_path"))
-	assert.EqualError(t, errs[4], fmt.Sprintf(errFmtReplacedConfigurationKey, "logs_level", "logging.level"))
+	assert.EqualError(t, errs[3], fmt.Sprintf(errFmtReplacedConfigurationKey, "logs_file_path", "log.file_path"))
+	assert.EqualError(t, errs[4], fmt.Sprintf(errFmtReplacedConfigurationKey, "logs_level", "log.level"))
 }
 
 func TestSecretKeysDontRaiseErrors(t *testing.T) {

internal/configuration/validator/logging.go

@@ -28,7 +28,7 @@ func ValidateLogging(configuration *schema.Configuration, validator *schema.Stru
 // TODO: DEPRECATED FUNCTION. Remove in 4.33.0.
 func applyDeprecatedLoggingConfiguration(configuration *schema.Configuration, validator *schema.StructValidator) {
 	if configuration.LogLevel != "" {
-		validator.PushWarning(fmt.Errorf(errFmtDeprecatedConfigurationKey, "log_level", "4.33.0", "logging.level"))
+		validator.PushWarning(fmt.Errorf(errFmtDeprecatedConfigurationKey, "log_level", "4.33.0", "log.level"))
 
 		if configuration.Logging.Level == "" {
 			configuration.Logging.Level = configuration.LogLevel
@@ -36,7 +36,7 @@ func applyDeprecatedLoggingConfiguration(configuration *schema.Configuration, va
 	}
 
 	if configuration.LogFormat != "" {
-		validator.PushWarning(fmt.Errorf(errFmtDeprecatedConfigurationKey, "log_format", "4.33.0", "logging.format"))
+		validator.PushWarning(fmt.Errorf(errFmtDeprecatedConfigurationKey, "log_format", "4.33.0", "log.format"))
 
 		if configuration.Logging.Format == "" {
 			configuration.Logging.Format = configuration.LogFormat
@@ -44,7 +44,7 @@ func applyDeprecatedLoggingConfiguration(configuration *schema.Configuration, va
 	}
 
 	if configuration.LogFilePath != "" {
-		validator.PushWarning(fmt.Errorf(errFmtDeprecatedConfigurationKey, "log_file_path", "4.33.0", "logging.file_path"))
+		validator.PushWarning(fmt.Errorf(errFmtDeprecatedConfigurationKey, "log_file_path", "4.33.0", "log.file_path"))
 
 		if configuration.Logging.FilePath == "" {
 			configuration.Logging.FilePath = configuration.LogFilePath

internal/configuration/validator/logging_test.go

@@ -33,7 +33,7 @@ func TestShouldSetDefaultLoggingValues(t *testing.T) {
 
 func TestShouldRaiseErrorOnInvalidLoggingLevel(t *testing.T) {
 	config := &schema.Configuration{
-		Logging: schema.LoggingConfiguration{
+		Logging: schema.LogConfiguration{
 			Level: "TRACE",
 		},
 	}
@@ -73,14 +73,14 @@ func TestShouldMigrateDeprecatedLoggingConfig(t *testing.T) {
 	assert.Equal(t, "json", config.Logging.Format)
 	assert.Equal(t, "/a/b/c", config.Logging.FilePath)
 
-	assert.EqualError(t, validator.Warnings()[0], fmt.Sprintf(errFmtDeprecatedConfigurationKey, "log_level", "4.33.0", "logging.level"))
-	assert.EqualError(t, validator.Warnings()[1], fmt.Sprintf(errFmtDeprecatedConfigurationKey, "log_format", "4.33.0", "logging.format"))
-	assert.EqualError(t, validator.Warnings()[2], fmt.Sprintf(errFmtDeprecatedConfigurationKey, "log_file_path", "4.33.0", "logging.file_path"))
+	assert.EqualError(t, validator.Warnings()[0], fmt.Sprintf(errFmtDeprecatedConfigurationKey, "log_level", "4.33.0", "log.level"))
+	assert.EqualError(t, validator.Warnings()[1], fmt.Sprintf(errFmtDeprecatedConfigurationKey, "log_format", "4.33.0", "log.format"))
+	assert.EqualError(t, validator.Warnings()[2], fmt.Sprintf(errFmtDeprecatedConfigurationKey, "log_file_path", "4.33.0", "log.file_path"))
 }
 
 func TestShouldRaiseErrorsAndNotOverwriteConfigurationWhenUsingDeprecatedLoggingConfig(t *testing.T) {
 	config := &schema.Configuration{
-		Logging: schema.LoggingConfiguration{
+		Logging: schema.LogConfiguration{
 			Level:      "info",
 			Format:     "text",
 			FilePath:   "/x/y/z",
@@ -105,7 +105,7 @@ func TestShouldRaiseErrorsAndNotOverwriteConfigurationWhenUsingDeprecatedLogging
 	assert.Len(t, validator.Errors(), 0)
 	require.Len(t, validator.Warnings(), 3)
 
-	assert.EqualError(t, validator.Warnings()[0], fmt.Sprintf(errFmtDeprecatedConfigurationKey, "log_level", "4.33.0", "logging.level"))
-	assert.EqualError(t, validator.Warnings()[1], fmt.Sprintf(errFmtDeprecatedConfigurationKey, "log_format", "4.33.0", "logging.format"))
-	assert.EqualError(t, validator.Warnings()[2], fmt.Sprintf(errFmtDeprecatedConfigurationKey, "log_file_path", "4.33.0", "logging.file_path"))
+	assert.EqualError(t, validator.Warnings()[0], fmt.Sprintf(errFmtDeprecatedConfigurationKey, "log_level", "4.33.0", "log.level"))
+	assert.EqualError(t, validator.Warnings()[1], fmt.Sprintf(errFmtDeprecatedConfigurationKey, "log_format", "4.33.0", "log.format"))
+	assert.EqualError(t, validator.Warnings()[2], fmt.Sprintf(errFmtDeprecatedConfigurationKey, "log_file_path", "4.33.0", "log.file_path"))
 }

internal/suites/ActiveDirectory/configuration.yml

@@ -9,7 +9,7 @@ tls_key: /config/ssl/key.pem
 
 theme: grey
 
-logging:
+log:
   level: debug
 
 default_redirection_url: https://home.example.com:8080/

internal/suites/BypassAll/configuration.yml

@@ -7,7 +7,7 @@ port: 9091
 tls_cert: /config/ssl/cert.pem
 tls_key: /config/ssl/key.pem
 
-logging:
+log:
   level: debug
 
 jwt_secret: unsecure_secret

internal/suites/CLI/configuration.yml

@@ -7,7 +7,7 @@ port: 9091
 tls_cert: /config/ssl/cert.pem
 tls_key: /config/ssl/key.pem
 
-logging:
+log:
   level: debug
 
 jwt_secret: unsecure_secret

internal/suites/Docker/configuration.yml

@@ -7,7 +7,7 @@ port: 9091
 tls_cert: /config/ssl/cert.pem
 tls_key: /config/ssl/key.pem
 
-logging:
+log:
   level: debug
 
 default_redirection_url: https://home.example.com:8080/

internal/suites/DuoPush/configuration.yml

@@ -7,7 +7,7 @@ port: 9091
 tls_cert: /config/ssl/cert.pem
 tls_key: /config/ssl/key.pem
 
-logging:
+log:
   level: trace
 
 default_redirection_url: https://home.example.com:8080/

internal/suites/HAProxy/configuration.yml

@@ -7,7 +7,7 @@ port: 9091
 tls_cert: /config/ssl/cert.pem
 tls_key: /config/ssl/key.pem
 
-logging:
+log:
   level: debug
 
 jwt_secret: unsecure_secret

internal/suites/HighAvailability/configuration.yml

@@ -7,7 +7,7 @@ port: 9091
 tls_cert: /config/ssl/cert.pem
 tls_key: /config/ssl/key.pem
 
-logging:
+log:
   level: debug
 
 jwt_secret: unsecure_secret

internal/suites/LDAP/configuration.yml

@@ -9,7 +9,7 @@ tls_key: /config/ssl/key.pem
 
 theme: dark
 
-logging:
+log:
   level: debug
 
 default_redirection_url: https://home.example.com:8080/

internal/suites/Mariadb/configuration.yml

@@ -7,7 +7,7 @@ port: 9091
 tls_cert: /config/ssl/cert.pem
 tls_key: /config/ssl/key.pem
 
-logging:
+log:
   level: debug
 
 default_redirection_url: https://home.example.com:8080/

internal/suites/MySQL/configuration.yml

@@ -7,7 +7,7 @@ port: 9091
 tls_cert: /config/ssl/cert.pem
 tls_key: /config/ssl/key.pem
 
-logging:
+log:
   level: debug
 
 default_redirection_url: https://home.example.com:8080/

internal/suites/NetworkACL/configuration.yml

@@ -7,7 +7,7 @@ port: 9091
 tls_cert: /config/ssl/cert.pem
 tls_key: /config/ssl/key.pem
 
-logging:
+log:
   level: debug
 
 jwt_secret: unsecure_password

internal/suites/OIDC/configuration.yml

@@ -3,7 +3,7 @@ port: 9091
 tls_cert: /config/ssl/cert.pem
 tls_key: /config/ssl/key.pem
 
-logging:
+log:
   level: debug
 
 jwt_secret: unsecure_secret

internal/suites/OIDCTraefik/configuration.yml

@@ -3,7 +3,7 @@ port: 9091
 tls_cert: /config/ssl/cert.pem
 tls_key: /config/ssl/key.pem
 
-logging:
+log:
   level: debug
 
 jwt_secret: unsecure_secret

internal/suites/OneFactorOnly/configuration.yml

@@ -7,7 +7,7 @@ port: 9091
 tls_cert: /config/ssl/cert.pem
 tls_key: /config/ssl/key.pem
 
-logging:
+log:
   level: debug
 
 default_redirection_url: https://home.example.com:8080/

internal/suites/PathPrefix/configuration.yml

@@ -10,7 +10,7 @@ tls_key: /config/ssl/key.pem
 server:
   path: auth
 
-logging:
+log:
   level: debug
 
 jwt_secret: unsecure_secret

internal/suites/Postgres/configuration.yml

@@ -7,7 +7,7 @@ port: 9091
 tls_cert: /config/ssl/cert.pem
 tls_key: /config/ssl/key.pem
 
-logging:
+log:
   level: debug
 
 default_redirection_url: https://home.example.com:8080/

internal/suites/ShortTimeouts/configuration.yml

@@ -7,7 +7,7 @@ port: 9091
 tls_cert: /config/ssl/cert.pem
 tls_key: /config/ssl/key.pem
 
-logging:
+log:
   level: debug
 
 jwt_secret: unsecure_secret

internal/suites/Standalone/configuration.yml

@@ -7,7 +7,7 @@ port: 9091
 tls_cert: /config/ssl/cert.pem
 tls_key: /config/ssl/key.pem
 
-logging:
+log:
   level: debug
 
 authentication_backend:

internal/suites/Traefik/configuration.yml

@@ -7,7 +7,7 @@ port: 9091
 tls_cert: /config/ssl/cert.pem
 tls_key: /config/ssl/key.pem
 
-logging:
+log:
   level: debug
 
 jwt_secret: unsecure_secret

internal/suites/Traefik2/configuration.yml

@@ -7,7 +7,7 @@ port: 9091
 tls_cert: /config/ssl/cert.pem
 tls_key: /config/ssl/key.pem
 
-logging:
+log:
   level: debug
 
 jwt_secret: unsecure_secret

internal/suites/example/kube/authelia/configs/configuration.yml

@@ -7,7 +7,7 @@ port: 443
 tls_cert: /config/ssl/cert.pem
 tls_key: /config/ssl/key.pem
 
-logging:
+log:
   level: debug
 
 default_redirection_url: https://home.example.com:8080