diff --git a/http/management.go b/http/management.go deleted file mode 100644 index 027e5ee..0000000 --- a/http/management.go +++ /dev/null @@ -1,84 +0,0 @@ -package http - -import ( - "net" - - "github.com/dioad/config/configcheck" - - dtls "github.com/dioad/net/tls" -) - -// ManagementConfig is the settings of a management listener a service takes -// under one nested block, usually "management". It serves health, /metrics and, -// with enable-debug, pprof, and has no authentication of its own. Check -// validates it and Operational maps it onto OperationalConfig. A service with -// settings of its own for the listener embeds ManagementConfig squashed in its -// own block type. OperationsConfig is the flat form of the same listener for -// services that have no such block. -type ManagementConfig struct { - // ListenAddress is the host:port of the listener. Empty means no listener, - // which a service that always runs one reports itself. - ListenAddress string `desc:"address of the management listener" mapstructure:"listen-address"` - - // AllowUnauthenticatedNonLoopback confirms that the listener may bind beyond - // loopback with nothing in front of it to authenticate callers. Check - // accepts a non-loopback address without it only when TLSServer requires - // client certificates. - AllowUnauthenticatedNonLoopback bool `desc:"allow the unauthenticated management listener to bind a non-loopback address" mapstructure:"allow-unauthenticated-non-loopback"` - - // EnablePrometheusMetrics serves /metrics. - EnablePrometheusMetrics bool `desc:"serve Prometheus metrics" mapstructure:"enable-prometheus-metrics"` - - // EnableDebug serves pprof. It exposes memory contents, so keep it to - // development. - EnableDebug bool `desc:"expose pprof and verbose diagnostics; development only" mapstructure:"enable-debug"` - - // EnableProxyProtocol accepts a PROXY protocol header, for a listener a - // proxy forwards to. - EnableProxyProtocol bool `desc:"accept a PROXY protocol header" mapstructure:"enable-proxy-protocol"` - - // TLSServer serves the listener over TLS. With client-auth-type - // RequireAndVerifyClientCert and a client-ca-file it also authenticates - // callers, which lets the listener bind beyond loopback unacknowledged. - TLSServer dtls.ServerConfig `desc:"TLS settings of the management listener" mapstructure:"tls-server"` -} - -// Check reports to c a listener that is malformed, one that is not loopback -// with nothing to authenticate its callers, an acknowledgement given with no -// listener to apply to, and a TLS block that does not check out. A listener is -// authenticated when TLSServer requires client certificates. c is positioned at -// the management block. -func (m ManagementConfig) Check(c *configcheck.Collector) { - m.TLSServer.Check(c.Field("tls-server")) - - address := c.Field("listen-address") - if m.ListenAddress == "" { - if m.AllowUnauthenticatedNonLoopback { - c.Field("allow-unauthenticated-non-loopback").Errorf("is set but has no effect without listen-address, remove it") - } - return - } - - configcheck.CheckListenAddress(address, m.ListenAddress) - if _, _, err := net.SplitHostPort(m.ListenAddress); err != nil { - return - } - if configcheck.IsLoopbackAddress(m.ListenAddress) || m.AllowUnauthenticatedNonLoopback || m.TLSServer.RequiresClientCertificate() { - return - } - address.Errorf("%q is reachable from other hosts and the management listener has no authentication; "+ - "bind to loopback, require client certificates (tls-server client-auth-type RequireAndVerifyClientCert with client-ca-file), "+ - "or set allow-unauthenticated-non-loopback if the network in front of it is trusted", m.ListenAddress) -} - -// Operational returns the OperationalConfig for the listener. Set TLSConfig on -// the result from TLSServer, and EnableStatus where the service has a status -// resource. -func (m ManagementConfig) Operational() OperationalConfig { - return OperationalConfig{ - ListenAddress: m.ListenAddress, - EnablePrometheusMetrics: m.EnablePrometheusMetrics, - EnableDebug: m.EnableDebug, - EnableProxyProtocol: m.EnableProxyProtocol, - } -} diff --git a/http/management_test.go b/http/management_test.go deleted file mode 100644 index ef722a5..0000000 --- a/http/management_test.go +++ /dev/null @@ -1,70 +0,0 @@ -package http - -import ( - "testing" - - "github.com/stretchr/testify/assert" - - "github.com/dioad/config/configcheck" - - dtls "github.com/dioad/net/tls" -) - -func TestManagementConfig_Check(t *testing.T) { - t.Parallel() - - mutualTLS := dtls.ServerConfig{ClientAuthType: "RequireAndVerifyClientCert", ClientCAFile: "ca.pem"} - unreachable := func(address string) configcheck.Finding { - return configcheck.Finding{ - Path: "listen-address", - Message: `"` + address + `" is reachable from other hosts and the management listener has no authentication; ` + - "bind to loopback, require client certificates (tls-server client-auth-type RequireAndVerifyClientCert with client-ca-file), " + - "or set allow-unauthenticated-non-loopback if the network in front of it is trusted", - } - } - - tests := []struct { - name string - cfg ManagementConfig - want []configcheck.Finding - }{ - {name: "no listener", cfg: ManagementConfig{}}, - {name: "loopback", cfg: ManagementConfig{ListenAddress: "127.0.0.1:9000"}}, - {name: "acknowledged non-loopback", cfg: ManagementConfig{ListenAddress: ":9000", AllowUnauthenticatedNonLoopback: true}}, - {name: "non-loopback that requires client certificates", cfg: ManagementConfig{ListenAddress: ":9000", TLSServer: mutualTLS}}, - {name: "non-loopback without acknowledgement", cfg: ManagementConfig{ListenAddress: ":9000"}, want: []configcheck.Finding{unreachable(":9000")}}, - { - name: "client certificates requested but not verified against a CA", - cfg: ManagementConfig{ListenAddress: ":9000", TLSServer: dtls.ServerConfig{ClientAuthType: "RequireAndVerifyClientCert"}}, - want: []configcheck.Finding{unreachable(":9000")}, - }, - { - name: "acknowledgement without a listener", - cfg: ManagementConfig{AllowUnauthenticatedNonLoopback: true}, - want: []configcheck.Finding{{Path: "allow-unauthenticated-non-loopback", Message: "is set but has no effect without listen-address, remove it"}}, - }, - { - name: "malformed address is reported once", - cfg: ManagementConfig{ListenAddress: "9000"}, - want: []configcheck.Finding{{Path: "listen-address", Message: `"9000": address 9000: missing port in address`}}, - }, - } - for _, tc := range tests { - t.Run(tc.name, func(t *testing.T) { - t.Parallel() - - c := configcheck.NewCollector() - tc.cfg.Check(c) - - assert.Equal(t, tc.want, c.Findings()) - }) - } -} - -func TestManagementConfig_OperationalCarriesTheListenerSettings(t *testing.T) { - t.Parallel() - - got := ManagementConfig{ListenAddress: "127.0.0.1:9000", EnablePrometheusMetrics: true, EnableDebug: true, EnableProxyProtocol: true}.Operational() - - assert.Equal(t, OperationalConfig{ListenAddress: "127.0.0.1:9000", EnablePrometheusMetrics: true, EnableDebug: true, EnableProxyProtocol: true}, got) -} diff --git a/http/operations.go b/http/operations.go index d4a18e3..e0a5bd6 100644 --- a/http/operations.go +++ b/http/operations.go @@ -5,6 +5,8 @@ import ( "time" "github.com/dioad/config/configcheck" + + dtls "github.com/dioad/net/tls" ) // ManagementAllowNonLoopbackKey is the setting that acknowledges a management @@ -15,18 +17,36 @@ const ManagementAllowNonLoopbackKey = "management-allow-unauthenticated-non-loop // OperationsConfig holds the operational settings a dioad service takes under // the same keys: the management listener, pprof, and the shutdown drain. A // service embeds it squashed, so the keys sit at the top level of its YAML and -// its flags. Check validates it, and ListenAddress, EnableDebug and -// AllowNonLoopback map onto OperationalConfig. +// its flags. Check validates it, and Operational maps it onto +// OperationalConfig. type OperationsConfig struct { // ManagementListenAddress is the host:port of the management listener that // serves health, /metrics and, with enable-debug, pprof. Empty disables it. ManagementListenAddress string `desc:"address of the management listener (health, metrics); empty disables it" mapstructure:"management-listen-address"` // ManagementAllowNonLoopback confirms that the management listener may bind - // beyond loopback. The listener has no authentication, so Check rejects a - // non-loopback address without it. + // beyond loopback with nothing in front of it to authenticate callers. Check + // accepts a non-loopback address without it only when ManagementTLSServer + // requires client certificates. ManagementAllowNonLoopback bool `desc:"allow the unauthenticated management listener to bind a non-loopback address" flag:"management-allow-unauthenticated-non-loopback" mapstructure:"management-allow-unauthenticated-non-loopback"` + // ManagementEnableProxyProtocol accepts a PROXY protocol header on the + // management listener, for one a proxy forwards to. Leave it off for a + // platform check or scraper that connects directly. + ManagementEnableProxyProtocol bool `desc:"accept a PROXY protocol header on the management listener" mapstructure:"management-enable-proxy-protocol"` + + // ManagementTLSServer serves the management listener over TLS. With + // client-auth-type RequireAndVerifyClientCert and a client-ca-file it also + // authenticates callers, which lets the listener bind beyond loopback + // without the acknowledgement. Convert it with tls.NewServerTLSConfig and + // set the result as OperationalConfig.TLSConfig. + ManagementTLSServer dtls.ServerConfig `desc:"TLS settings of the management listener" mapstructure:"management-tls-server"` + + // EnablePrometheusMetrics serves /metrics on the management listener. Unset + // means on: the listener exists for health and metrics, and a service has to + // set it false to turn them off. + EnablePrometheusMetrics *bool `desc:"serve Prometheus metrics on the management listener (default true)" mapstructure:"enable-prometheus-metrics"` + // EnableDebug should only be true in development environments. Set to false // in production to avoid exposing sensitive information. EnableDebug bool `desc:"expose pprof and verbose diagnostics; development only" mapstructure:"enable-debug"` @@ -39,15 +59,18 @@ type OperationsConfig struct { } // Check reports to c a management listener that is malformed or, without the -// acknowledgement, not loopback, an acknowledgement given with no listener to -// apply to, and a negative drain delay. The management listener serves -// health, /metrics and, with enable-debug, pprof, with no authentication and -// no TLS, so binding it beyond loopback has to be a deliberate choice. c is +// acknowledgement, not loopback and not protected by client certificates, an +// acknowledgement given with no listener to apply to, a TLS block that does not +// check out, and a negative drain delay. The management listener serves +// health, /metrics and, with enable-debug, pprof, with no authentication of its +// own, so binding it beyond loopback has to be a deliberate choice. c is // positioned at the service's configuration root. func (o OperationsConfig) Check(c *configcheck.Collector) { + o.ManagementTLSServer.Check(c.Field("management-tls-server")) + address := c.Field("management-listen-address") - switch { - case o.ManagementListenAddress == "": + switch o.ManagementListenAddress { + case "": if o.ManagementAllowNonLoopback { c.Field(ManagementAllowNonLoopbackKey).Errorf("is set but has no effect without management-listen-address, remove it") } @@ -56,9 +79,11 @@ func (o OperationsConfig) Check(c *configcheck.Collector) { if _, _, err := net.SplitHostPort(o.ManagementListenAddress); err != nil { break } - if !o.ManagementAllowNonLoopback && !configcheck.IsLoopbackAddress(o.ManagementListenAddress) { + if !o.ManagementAllowNonLoopback && !configcheck.IsLoopbackAddress(o.ManagementListenAddress) && + !o.ManagementTLSServer.RequiresClientCertificate() { address.Errorf("%q is not a loopback address, and the management listener has no authentication; "+ - "bind 127.0.0.1 or set %s: true to confirm the port is reachable only on a private network", + "bind 127.0.0.1, require client certificates (management-tls-server client-auth-type RequireAndVerifyClientCert with client-ca-file), "+ + "or set %s: true to confirm the port is reachable only on a private network", o.ManagementListenAddress, ManagementAllowNonLoopbackKey) } } @@ -68,13 +93,15 @@ func (o OperationsConfig) Check(c *configcheck.Collector) { } // Operational returns the OperationalConfig for the management listener: -// health, /metrics, and /debug when EnableDebug is set. Pass WithReadiness to -// NewOperationalServer so /health/ready reports the service's readiness, and set -// any TLS or PROXY protocol settings on the result. +// health, /metrics unless turned off, and /debug when EnableDebug is set. Pass +// WithReadiness to NewOperationalServer so /health/ready reports the service's +// readiness, and set TLSConfig on the result from ManagementTLSServer and +// EnableStatus where the service has a status resource. func (o OperationsConfig) Operational() OperationalConfig { return OperationalConfig{ ListenAddress: o.ManagementListenAddress, - EnablePrometheusMetrics: true, + EnablePrometheusMetrics: o.EnablePrometheusMetrics == nil || *o.EnablePrometheusMetrics, EnableDebug: o.EnableDebug, + EnableProxyProtocol: o.ManagementEnableProxyProtocol, } } diff --git a/http/operations_test.go b/http/operations_test.go index 38a0a95..4b5b90a 100644 --- a/http/operations_test.go +++ b/http/operations_test.go @@ -12,6 +12,8 @@ import ( "github.com/stretchr/testify/require" "github.com/dioad/config/configcheck" + + dtls "github.com/dioad/net/tls" ) func TestOperationsConfig_Check(t *testing.T) { @@ -26,12 +28,28 @@ func TestOperationsConfig_Check(t *testing.T) { {name: "loopback", cfg: OperationsConfig{ManagementListenAddress: "127.0.0.1:9000"}}, {name: "localhost", cfg: OperationsConfig{ManagementListenAddress: "localhost:9000"}}, {name: "acknowledged non-loopback", cfg: OperationsConfig{ManagementListenAddress: ":9000", ManagementAllowNonLoopback: true}}, + { + name: "non-loopback that requires client certificates", + cfg: OperationsConfig{ManagementListenAddress: ":9000", ManagementTLSServer: dtls.ServerConfig{ + ClientAuthType: "RequireAndVerifyClientCert", ClientCAFile: "ca.pem", + }}, + }, + { + name: "client certificates requested but not verified against a CA", + cfg: OperationsConfig{ManagementListenAddress: ":9000", ManagementTLSServer: dtls.ServerConfig{ + ClientAuthType: "RequireAndVerifyClientCert", + }}, + want: []configcheck.Finding{{ + Path: "management-listen-address", + Message: `":9000" is not a loopback address, and the management listener has no authentication; bind 127.0.0.1, require client certificates (management-tls-server client-auth-type RequireAndVerifyClientCert with client-ca-file), or set management-allow-unauthenticated-non-loopback: true to confirm the port is reachable only on a private network`, + }}, + }, { name: "wildcard host without acknowledgement", cfg: OperationsConfig{ManagementListenAddress: ":9000"}, want: []configcheck.Finding{{ Path: "management-listen-address", - Message: `":9000" is not a loopback address, and the management listener has no authentication; bind 127.0.0.1 or set management-allow-unauthenticated-non-loopback: true to confirm the port is reachable only on a private network`, + Message: `":9000" is not a loopback address, and the management listener has no authentication; bind 127.0.0.1, require client certificates (management-tls-server client-auth-type RequireAndVerifyClientCert with client-ca-file), or set management-allow-unauthenticated-non-loopback: true to confirm the port is reachable only on a private network`, }}, }, { @@ -65,12 +83,38 @@ func TestOperationsConfig_Check(t *testing.T) { } } -func TestOperationsConfig_OperationalServesMetricsAndHonoursDebug(t *testing.T) { +func TestOperationsConfig_Operational(t *testing.T) { t.Parallel() - got := OperationsConfig{ManagementListenAddress: "127.0.0.1:9000", EnableDebug: true}.Operational() + off := false + tests := []struct { + name string + cfg OperationsConfig + want OperationalConfig + }{ + { + name: "metrics are on unless turned off, and debug follows the flag", + cfg: OperationsConfig{ManagementListenAddress: "127.0.0.1:9000", EnableDebug: true}, + want: OperationalConfig{ListenAddress: "127.0.0.1:9000", EnablePrometheusMetrics: true, EnableDebug: true}, + }, + { + name: "metrics can be turned off", + cfg: OperationsConfig{ManagementListenAddress: "127.0.0.1:9000", EnablePrometheusMetrics: &off}, + want: OperationalConfig{ListenAddress: "127.0.0.1:9000"}, + }, + { + name: "PROXY protocol is carried over", + cfg: OperationsConfig{ManagementListenAddress: "127.0.0.1:9000", ManagementEnableProxyProtocol: true}, + want: OperationalConfig{ListenAddress: "127.0.0.1:9000", EnablePrometheusMetrics: true, EnableProxyProtocol: true}, + }, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + t.Parallel() - assert.Equal(t, OperationalConfig{ListenAddress: "127.0.0.1:9000", EnablePrometheusMetrics: true, EnableDebug: true}, got) + assert.Equal(t, tc.want, tc.cfg.Operational()) + }) + } } type readyStub struct{ err error }