diff --git a/cli/testdata/coder_server_--help.golden b/cli/testdata/coder_server_--help.golden index d5c26d98115cb..cd647d0537a93 100644 --- a/cli/testdata/coder_server_--help.golden +++ b/cli/testdata/coder_server_--help.golden @@ -106,6 +106,58 @@ Use a YAML configuration file when your server launch become unwieldy. Write out the current server config as YAML to stdout. +EMAIL OPTIONS: +Configure how emails are sent. + + --email-force-tls bool, $CODER_EMAIL_FORCE_TLS (default: false) + Force a TLS connection to the configured SMTP smarthost. + + --email-from string, $CODER_EMAIL_FROM + The sender's address to use. + + --email-hello string, $CODER_EMAIL_HELLO (default: localhost) + The hostname identifying the SMTP server. + + --email-smarthost host:port, $CODER_EMAIL_SMARTHOST (default: localhost:587) + The intermediary SMTP host through which emails are sent. + +EMAIL / EMAIL AUTHENTICATION OPTIONS: +Configure SMTP authentication options. + + --email-auth-identity string, $CODER_EMAIL_AUTH_IDENTITY + Identity to use with PLAIN authentication. + + --email-auth-password string, $CODER_EMAIL_AUTH_PASSWORD + Password to use with PLAIN/LOGIN authentication. + + --email-auth-password-file string, $CODER_EMAIL_AUTH_PASSWORD_FILE + File from which to load password for use with PLAIN/LOGIN + authentication. + + --email-auth-username string, $CODER_EMAIL_AUTH_USERNAME + Username to use with PLAIN/LOGIN authentication. + +EMAIL / EMAIL TLS OPTIONS: +Configure TLS for your SMTP server target. + + --email-tls-ca-cert-file string, $CODER_EMAIL_TLS_CACERTFILE + CA certificate file to use. + + --email-tls-cert-file string, $CODER_EMAIL_TLS_CERTFILE + Certificate file to use. + + --email-tls-cert-key-file string, $CODER_EMAIL_TLS_CERTKEYFILE + Certificate key file to use. + + --email-tls-server-name string, $CODER_EMAIL_TLS_SERVERNAME + Server name to verify against the target certificate. + + --email-tls-skip-verify bool, $CODER_EMAIL_TLS_SKIPVERIFY + Skip verification of the target server's certificate (insecure). + + --email-tls-starttls bool, $CODER_EMAIL_TLS_STARTTLS + Enable STARTTLS to upgrade insecure SMTP connections using TLS. + INTROSPECTION / HEALTH CHECK OPTIONS: --health-check-refresh duration, $CODER_HEALTH_CHECK_REFRESH (default: 10m0s) Refresh interval for healthchecks. @@ -349,54 +401,68 @@ Configure how notifications are processed and delivered. NOTIFICATIONS / EMAIL OPTIONS: Configure how email notifications are sent. - --notifications-email-force-tls bool, $CODER_NOTIFICATIONS_EMAIL_FORCE_TLS (default: false) + --notifications-email-force-tls bool, $CODER_NOTIFICATIONS_EMAIL_FORCE_TLS Force a TLS connection to the configured SMTP smarthost. + DEPRECATED: Use --email-force-tls instead. --notifications-email-from string, $CODER_NOTIFICATIONS_EMAIL_FROM The sender's address to use. + DEPRECATED: Use --email-from instead. - --notifications-email-hello string, $CODER_NOTIFICATIONS_EMAIL_HELLO (default: localhost) + --notifications-email-hello string, $CODER_NOTIFICATIONS_EMAIL_HELLO The hostname identifying the SMTP server. + DEPRECATED: Use --email-hello instead. - --notifications-email-smarthost host:port, $CODER_NOTIFICATIONS_EMAIL_SMARTHOST (default: localhost:587) + --notifications-email-smarthost host:port, $CODER_NOTIFICATIONS_EMAIL_SMARTHOST The intermediary SMTP host through which emails are sent. + DEPRECATED: Use --email-smarthost instead. NOTIFICATIONS / EMAIL / EMAIL AUTHENTICATION OPTIONS: Configure SMTP authentication options. --notifications-email-auth-identity string, $CODER_NOTIFICATIONS_EMAIL_AUTH_IDENTITY Identity to use with PLAIN authentication. + DEPRECATED: Use --email-auth-identity instead. --notifications-email-auth-password string, $CODER_NOTIFICATIONS_EMAIL_AUTH_PASSWORD Password to use with PLAIN/LOGIN authentication. + DEPRECATED: Use --email-auth-password instead. --notifications-email-auth-password-file string, $CODER_NOTIFICATIONS_EMAIL_AUTH_PASSWORD_FILE File from which to load password for use with PLAIN/LOGIN authentication. + DEPRECATED: Use --email-auth-password-file instead. --notifications-email-auth-username string, $CODER_NOTIFICATIONS_EMAIL_AUTH_USERNAME Username to use with PLAIN/LOGIN authentication. + DEPRECATED: Use --email-auth-username instead. NOTIFICATIONS / EMAIL / EMAIL TLS OPTIONS: Configure TLS for your SMTP server target. --notifications-email-tls-ca-cert-file string, $CODER_NOTIFICATIONS_EMAIL_TLS_CACERTFILE CA certificate file to use. + DEPRECATED: Use --email-tls-ca-cert-file instead. --notifications-email-tls-cert-file string, $CODER_NOTIFICATIONS_EMAIL_TLS_CERTFILE Certificate file to use. + DEPRECATED: Use --email-tls-cert-file instead. --notifications-email-tls-cert-key-file string, $CODER_NOTIFICATIONS_EMAIL_TLS_CERTKEYFILE Certificate key file to use. + DEPRECATED: Use --email-tls-cert-key-file instead. --notifications-email-tls-server-name string, $CODER_NOTIFICATIONS_EMAIL_TLS_SERVERNAME Server name to verify against the target certificate. + DEPRECATED: Use --email-tls-server-name instead. --notifications-email-tls-skip-verify bool, $CODER_NOTIFICATIONS_EMAIL_TLS_SKIPVERIFY Skip verification of the target server's certificate (insecure). + DEPRECATED: Use --email-tls-skip-verify instead. --notifications-email-tls-starttls bool, $CODER_NOTIFICATIONS_EMAIL_TLS_STARTTLS Enable STARTTLS to upgrade insecure SMTP connections using TLS. + DEPRECATED: Use --email-tls-starttls instead. NOTIFICATIONS / WEBHOOK OPTIONS: --notifications-webhook-endpoint url, $CODER_NOTIFICATIONS_WEBHOOK_ENDPOINT diff --git a/cli/testdata/server-config.yaml.golden b/cli/testdata/server-config.yaml.golden index 95486a26344b8..38b2b68c24de1 100644 --- a/cli/testdata/server-config.yaml.golden +++ b/cli/testdata/server-config.yaml.golden @@ -518,6 +518,51 @@ userQuietHoursSchedule: # compatibility reasons, this will be removed in a future release. # (default: false, type: bool) allowWorkspaceRenames: false +# Configure how emails are sent. +email: + # The sender's address to use. + # (default: , type: string) + from: "" + # The intermediary SMTP host through which emails are sent. + # (default: localhost:587, type: host:port) + smarthost: localhost:587 + # The hostname identifying the SMTP server. + # (default: localhost, type: string) + hello: localhost + # Force a TLS connection to the configured SMTP smarthost. + # (default: false, type: bool) + forceTLS: false + # Configure SMTP authentication options. + emailAuth: + # Identity to use with PLAIN authentication. + # (default: , type: string) + identity: "" + # Username to use with PLAIN/LOGIN authentication. + # (default: , type: string) + username: "" + # File from which to load password for use with PLAIN/LOGIN authentication. + # (default: , type: string) + passwordFile: "" + # Configure TLS for your SMTP server target. + emailTLS: + # Enable STARTTLS to upgrade insecure SMTP connections using TLS. + # (default: , type: bool) + startTLS: false + # Server name to verify against the target certificate. + # (default: , type: string) + serverName: "" + # Skip verification of the target server's certificate (insecure). + # (default: , type: bool) + insecureSkipVerify: false + # CA certificate file to use. + # (default: , type: string) + caCertFile: "" + # Certificate file to use. + # (default: , type: string) + certFile: "" + # Certificate key file to use. + # (default: , type: string) + certKeyFile: "" # Configure how notifications are processed and delivered. notifications: # Which delivery method to use (available options: 'smtp', 'webhook'). @@ -532,13 +577,13 @@ notifications: # (default: , type: string) from: "" # The intermediary SMTP host through which emails are sent. - # (default: localhost:587, type: host:port) + # (default: , type: host:port) smarthost: localhost:587 # The hostname identifying the SMTP server. - # (default: localhost, type: string) + # (default: , type: string) hello: localhost # Force a TLS connection to the configured SMTP smarthost. - # (default: false, type: bool) + # (default: , type: bool) forceTLS: false # Configure SMTP authentication options. emailAuth: diff --git a/coderd/notifications/dispatch/smtp.go b/coderd/notifications/dispatch/smtp.go index e18aeaef88b81..dfb628b62eb86 100644 --- a/coderd/notifications/dispatch/smtp.go +++ b/coderd/notifications/dispatch/smtp.go @@ -453,7 +453,7 @@ func (s *SMTPHandler) auth(ctx context.Context, mechs string) (sasl.Client, erro continue } if password == "" { - errs = multierror.Append(errs, xerrors.New("cannot use PLAIN auth, password not defined (see CODER_NOTIFICATIONS_EMAIL_AUTH_PASSWORD)")) + errs = multierror.Append(errs, xerrors.New("cannot use PLAIN auth, password not defined (see CODER_EMAIL_AUTH_PASSWORD)")) continue } @@ -475,7 +475,7 @@ func (s *SMTPHandler) auth(ctx context.Context, mechs string) (sasl.Client, erro continue } if password == "" { - errs = multierror.Append(errs, xerrors.New("cannot use LOGIN auth, password not defined (see CODER_NOTIFICATIONS_EMAIL_AUTH_PASSWORD)")) + errs = multierror.Append(errs, xerrors.New("cannot use LOGIN auth, password not defined (see CODER_EMAIL_AUTH_PASSWORD)")) continue } diff --git a/codersdk/deployment.go b/codersdk/deployment.go index 6a5f7c52ac8f5..3ba09bd38d1a4 100644 --- a/codersdk/deployment.go +++ b/codersdk/deployment.go @@ -926,6 +926,23 @@ when required by your organization's security policy.`, Name: "Config", Description: `Use a YAML configuration file when your server launch become unwieldy.`, } + deploymentGroupEmail = serpent.Group{ + Name: "Email", + Description: "Configure how emails are sent.", + YAML: "email", + } + deploymentGroupEmailAuth = serpent.Group{ + Name: "Email Authentication", + Parent: &deploymentGroupEmail, + Description: "Configure SMTP authentication options.", + YAML: "emailAuth", + } + deploymentGroupEmailTLS = serpent.Group{ + Name: "Email TLS", + Parent: &deploymentGroupEmail, + Description: "Configure TLS for your SMTP server target.", + YAML: "emailTLS", + } deploymentGroupNotifications = serpent.Group{ Name: "Notifications", YAML: "notifications", @@ -997,6 +1014,135 @@ when required by your organization's security policy.`, Group: &deploymentGroupIntrospectionLogging, YAML: "filter", } + emailFrom := serpent.Option{ + Name: "Email: From Address", + Description: "The sender's address to use.", + Flag: "email-from", + Env: "CODER_EMAIL_FROM", + Value: &c.Notifications.SMTP.From, + Group: &deploymentGroupEmail, + YAML: "from", + } + emailSmarthost := serpent.Option{ + Name: "Email: Smarthost", + Description: "The intermediary SMTP host through which emails are sent.", + Flag: "email-smarthost", + Env: "CODER_EMAIL_SMARTHOST", + Default: "localhost:587", // To pass validation. + Value: &c.Notifications.SMTP.Smarthost, + Group: &deploymentGroupEmail, + YAML: "smarthost", + } + emailHello := serpent.Option{ + Name: "Email: Hello", + Description: "The hostname identifying the SMTP server.", + Flag: "email-hello", + Env: "CODER_EMAIL_HELLO", + Default: "localhost", + Value: &c.Notifications.SMTP.Hello, + Group: &deploymentGroupEmail, + YAML: "hello", + } + emailForceTLS := serpent.Option{ + Name: "Email: Force TLS", + Description: "Force a TLS connection to the configured SMTP smarthost.", + Flag: "email-force-tls", + Env: "CODER_EMAIL_FORCE_TLS", + Default: "false", + Value: &c.Notifications.SMTP.ForceTLS, + Group: &deploymentGroupEmail, + YAML: "forceTLS", + } + emailAuthIdentity := serpent.Option{ + Name: "Email Auth: Identity", + Description: "Identity to use with PLAIN authentication.", + Flag: "email-auth-identity", + Env: "CODER_EMAIL_AUTH_IDENTITY", + Value: &c.Notifications.SMTP.Auth.Identity, + Group: &deploymentGroupEmailAuth, + YAML: "identity", + } + emailAuthUsername := serpent.Option{ + Name: "Email Auth: Username", + Description: "Username to use with PLAIN/LOGIN authentication.", + Flag: "email-auth-username", + Env: "CODER_EMAIL_AUTH_USERNAME", + Value: &c.Notifications.SMTP.Auth.Username, + Group: &deploymentGroupEmailAuth, + YAML: "username", + } + emailAuthPassword := serpent.Option{ + Name: "Email Auth: Password", + Description: "Password to use with PLAIN/LOGIN authentication.", + Flag: "email-auth-password", + Env: "CODER_EMAIL_AUTH_PASSWORD", + Annotations: serpent.Annotations{}.Mark(annotationSecretKey, "true"), + Value: &c.Notifications.SMTP.Auth.Password, + Group: &deploymentGroupEmailAuth, + } + emailAuthPasswordFile := serpent.Option{ + Name: "Email Auth: Password File", + Description: "File from which to load password for use with PLAIN/LOGIN authentication.", + Flag: "email-auth-password-file", + Env: "CODER_EMAIL_AUTH_PASSWORD_FILE", + Value: &c.Notifications.SMTP.Auth.PasswordFile, + Group: &deploymentGroupEmailAuth, + YAML: "passwordFile", + } + emailTLSStartTLS := serpent.Option{ + Name: "Email TLS: StartTLS", + Description: "Enable STARTTLS to upgrade insecure SMTP connections using TLS.", + Flag: "email-tls-starttls", + Env: "CODER_EMAIL_TLS_STARTTLS", + Value: &c.Notifications.SMTP.TLS.StartTLS, + Group: &deploymentGroupEmailTLS, + YAML: "startTLS", + } + emailTLSServerName := serpent.Option{ + Name: "Email TLS: Server Name", + Description: "Server name to verify against the target certificate.", + Flag: "email-tls-server-name", + Env: "CODER_EMAIL_TLS_SERVERNAME", + Value: &c.Notifications.SMTP.TLS.ServerName, + Group: &deploymentGroupEmailTLS, + YAML: "serverName", + } + emailTLSSkipCertVerify := serpent.Option{ + Name: "Email TLS: Skip Certificate Verification (Insecure)", + Description: "Skip verification of the target server's certificate (insecure).", + Flag: "email-tls-skip-verify", + Env: "CODER_EMAIL_TLS_SKIPVERIFY", + Value: &c.Notifications.SMTP.TLS.InsecureSkipVerify, + Group: &deploymentGroupEmailTLS, + YAML: "insecureSkipVerify", + } + emailTLSCertAuthorityFile := serpent.Option{ + Name: "Email TLS: Certificate Authority File", + Description: "CA certificate file to use.", + Flag: "email-tls-ca-cert-file", + Env: "CODER_EMAIL_TLS_CACERTFILE", + Value: &c.Notifications.SMTP.TLS.CAFile, + Group: &deploymentGroupEmailTLS, + YAML: "caCertFile", + } + emailTLSCertFile := serpent.Option{ + Name: "Email TLS: Certificate File", + Description: "Certificate file to use.", + Flag: "email-tls-cert-file", + Env: "CODER_EMAIL_TLS_CERTFILE", + Value: &c.Notifications.SMTP.TLS.CertFile, + Group: &deploymentGroupEmailTLS, + YAML: "certFile", + } + emailTLSCertKeyFile := serpent.Option{ + Name: "Email TLS: Certificate Key File", + Description: "Certificate key file to use.", + Flag: "email-tls-cert-key-file", + Env: "CODER_EMAIL_TLS_CERTKEYFILE", + Value: &c.Notifications.SMTP.TLS.KeyFile, + Group: &deploymentGroupEmailTLS, + YAML: "certKeyFile", + } opts := serpent.OptionSet{ { Name: "Access URL", @@ -2432,6 +2578,21 @@ Write out the current server config as YAML to stdout.`, YAML: "thresholdDatabase", Annotations: serpent.Annotations{}.Mark(annotationFormatDuration, "true"), }, + // Email options + emailFrom, + emailSmarthost, + emailHello, + emailForceTLS, + emailAuthIdentity, + emailAuthUsername, + emailAuthPassword, + emailAuthPasswordFile, + emailTLSStartTLS, + emailTLSServerName, + emailTLSSkipCertVerify, + emailTLSCertAuthorityFile, + emailTLSCertFile, + emailTLSCertKeyFile, // Notifications Options { Name: "Notifications: Method", @@ -2462,36 +2623,37 @@ Write out the current server config as YAML to stdout.`, Value: &c.Notifications.SMTP.From, Group: &deploymentGroupNotificationsEmail, YAML: "from", + UseInstead: serpent.OptionSet{emailFrom}, }, { Name: "Notifications: Email: Smarthost", Description: "The intermediary SMTP host through which emails are sent.", Flag: "notifications-email-smarthost", Env: "CODER_NOTIFICATIONS_EMAIL_SMARTHOST", - Default: "localhost:587", // To pass validation. Value: &c.Notifications.SMTP.Smarthost, Group: &deploymentGroupNotificationsEmail, YAML: "smarthost", + UseInstead: serpent.OptionSet{emailSmarthost}, }, { Name: "Notifications: Email: Hello", Description: "The hostname identifying the SMTP server.", Flag: "notifications-email-hello", Env: "CODER_NOTIFICATIONS_EMAIL_HELLO", - Default: "localhost", Value: &c.Notifications.SMTP.Hello, Group: &deploymentGroupNotificationsEmail, YAML: "hello", + UseInstead: serpent.OptionSet{emailHello}, }, { Name: "Notifications: Email: Force TLS", Description: "Force a TLS connection to the configured SMTP smarthost.", Flag: "notifications-email-force-tls", Env: "CODER_NOTIFICATIONS_EMAIL_FORCE_TLS", - Default: "false", Value: &c.Notifications.SMTP.ForceTLS, Group: &deploymentGroupNotificationsEmail, YAML: "forceTLS", + UseInstead: serpent.OptionSet{emailForceTLS}, }, { Name: "Notifications: Email Auth: Identity", @@ -2501,6 +2663,7 @@ Write out the current server config as YAML to stdout.`, Value: &c.Notifications.SMTP.Auth.Identity, Group: &deploymentGroupNotificationsEmailAuth, YAML: "identity", + UseInstead: serpent.OptionSet{emailAuthIdentity}, }, { Name: "Notifications: Email Auth: Username", @@ -2510,6 +2673,7 @@ Write out the current server config as YAML to stdout.`, Value: &c.Notifications.SMTP.Auth.Username, Group: &deploymentGroupNotificationsEmailAuth, YAML: "username", + UseInstead: serpent.OptionSet{emailAuthUsername}, }, { Name: "Notifications: Email Auth: Password", @@ -2519,6 +2683,7 @@ Write out the current server config as YAML to stdout.`, Annotations: serpent.Annotations{}.Mark(annotationSecretKey, "true"), Value: &c.Notifications.SMTP.Auth.Password, Group: &deploymentGroupNotificationsEmailAuth, + UseInstead: serpent.OptionSet{emailAuthPassword}, }, { Name: "Notifications: Email Auth: Password File", @@ -2528,6 +2693,7 @@ Write out the current server config as YAML to stdout.`, Value: &c.Notifications.SMTP.Auth.PasswordFile, Group: &deploymentGroupNotificationsEmailAuth, YAML: "passwordFile", + UseInstead: serpent.OptionSet{emailAuthPasswordFile}, }, { Name: "Notifications: Email TLS: StartTLS", @@ -2537,6 +2703,7 @@ Write out the current server config as YAML to stdout.`, Value: &c.Notifications.SMTP.TLS.StartTLS, Group: &deploymentGroupNotificationsEmailTLS, YAML: "startTLS", + UseInstead: serpent.OptionSet{emailTLSStartTLS}, }, { Name: "Notifications: Email TLS: Server Name", @@ -2546,6 +2713,7 @@ Write out the current server config as YAML to stdout.`, Value: &c.Notifications.SMTP.TLS.ServerName, Group: &deploymentGroupNotificationsEmailTLS, YAML: "serverName", + UseInstead: serpent.OptionSet{emailTLSServerName}, }, { Name: "Notifications: Email TLS: Skip Certificate Verification (Insecure)", @@ -2555,6 +2723,7 @@ Write out the current server config as YAML to stdout.`, Value: &c.Notifications.SMTP.TLS.InsecureSkipVerify, Group: &deploymentGroupNotificationsEmailTLS, YAML: "insecureSkipVerify", + UseInstead: serpent.OptionSet{emailTLSSkipCertVerify}, }, { Name: "Notifications: Email TLS: Certificate Authority File", @@ -2564,6 +2733,7 @@ Write out the current server config as YAML to stdout.`, Value: &c.Notifications.SMTP.TLS.CAFile, Group: &deploymentGroupNotificationsEmailTLS, YAML: "caCertFile", + UseInstead: serpent.OptionSet{emailTLSCertAuthorityFile}, }, { Name: "Notifications: Email TLS: Certificate File", @@ -2573,6 +2743,7 @@ Write out the current server config as YAML to stdout.`, Value: &c.Notifications.SMTP.TLS.CertFile, Group: &deploymentGroupNotificationsEmailTLS, YAML: "certFile", + UseInstead: serpent.OptionSet{emailTLSCertFile}, }, { Name: "Notifications: Email TLS: Certificate Key File", @@ -2582,6 +2753,7 @@ Write out the current server config as YAML to stdout.`, Value: &c.Notifications.SMTP.TLS.KeyFile, Group: &deploymentGroupNotificationsEmailTLS, YAML: "certKeyFile", + UseInstead: serpent.OptionSet{emailTLSCertKeyFile}, }, { Name: "Notifications: Webhook: Endpoint", diff --git a/codersdk/deployment_test.go b/codersdk/deployment_test.go index d7eca6323000c..61474a3b77ea1 100644 --- a/codersdk/deployment_test.go +++ b/codersdk/deployment_test.go @@ -78,6 +78,9 @@ func TestDeploymentValues_HighlyConfigurable(t *testing.T) { "Provisioner Daemon Pre-shared Key (PSK)": { yaml: true, }, + "Email Auth: Password": { + yaml: true, + }, "Notifications: Email Auth: Password": { yaml: true, }, diff --git a/docs/admin/monitoring/notifications/index.md b/docs/admin/monitoring/notifications/index.md index a98fa0b3e8b48..eabc09438d7b9 100644 --- a/docs/admin/monitoring/notifications/index.md +++ b/docs/admin/monitoring/notifications/index.md @@ -89,34 +89,34 @@ existing one. **Server Settings:** -| Required | CLI | Env | Type | Description | Default | -| :------: | --------------------------------- | ------------------------------------- | ----------- | ----------------------------------------- | ------------- | -| ✔️ | `--notifications-email-from` | `CODER_NOTIFICATIONS_EMAIL_FROM` | `string` | The sender's address to use. | | -| ✔️ | `--notifications-email-smarthost` | `CODER_NOTIFICATIONS_EMAIL_SMARTHOST` | `host:port` | The SMTP relay to send messages through. | localhost:587 | -| ✔️ | `--notifications-email-hello` | `CODER_NOTIFICATIONS_EMAIL_HELLO` | `string` | The hostname identifying the SMTP server. | localhost | +| Required | CLI | Env | Type | Description | Default | +| :------: | ------------------- | ----------------------- | ----------- | ----------------------------------------- | ------------- | +| ✔️ | `--email-from` | `CODER_EMAIL_FROM` | `string` | The sender's address to use. | | +| ✔️ | `--email-smarthost` | `CODER_EMAIL_SMARTHOST` | `host:port` | The SMTP relay to send messages through. | localhost:587 | +| ✔️ | `--email-hello` | `CODER_EMAIL_HELLO` | `string` | The hostname identifying the SMTP server. | localhost | **Authentication Settings:** -| Required | CLI | Env | Type | Description | -| :------: | ------------------------------------------ | ---------------------------------------------- | -------- | ------------------------------------------------------------------------- | -| - | `--notifications-email-auth-username` | `CODER_NOTIFICATIONS_EMAIL_AUTH_USERNAME` | `string` | Username to use with PLAIN/LOGIN authentication. | -| - | `--notifications-email-auth-password` | `CODER_NOTIFICATIONS_EMAIL_AUTH_PASSWORD` | `string` | Password to use with PLAIN/LOGIN authentication. | -| - | `--notifications-email-auth-password-file` | `CODER_NOTIFICATIONS_EMAIL_AUTH_PASSWORD_FILE` | `string` | File from which to load password for use with PLAIN/LOGIN authentication. | -| - | `--notifications-email-auth-identity` | `CODER_NOTIFICATIONS_EMAIL_AUTH_IDENTITY` | `string` | Identity to use with PLAIN authentication. | +| Required | CLI | Env | Type | Description | +| :------: | ---------------------------- | -------------------------------- | -------- | ------------------------------------------------------------------------- | +| - | `--email-auth-username` | `CODER_EMAIL_AUTH_USERNAME` | `string` | Username to use with PLAIN/LOGIN authentication. | +| - | `--email-auth-password` | `CODER_EMAIL_AUTH_PASSWORD` | `string` | Password to use with PLAIN/LOGIN authentication. | +| - | `--email-auth-password-file` | `CODER_EMAIL_AUTH_PASSWORD_FILE` | `string` | File from which to load password for use with PLAIN/LOGIN authentication. | +| - | `--email-auth-identity` | `CODER_EMAIL_AUTH_IDENTITY` | `string` | Identity to use with PLAIN authentication. | **TLS Settings:** -| Required | CLI | Env | Type | Description | Default | -| :------: | ----------------------------------------- | ------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -| - | `--notifications-email-force-tls` | `CODER_NOTIFICATIONS_EMAIL_FORCE_TLS` | `bool` | Force a TLS connection to the configured SMTP smarthost. If port 465 is used, TLS will be forced. See https://datatracker.ietf.org/doc/html/rfc8314#section-3.3. | false | -| - | `--notifications-email-tls-starttls` | `CODER_NOTIFICATIONS_EMAIL_TLS_STARTTLS` | `bool` | Enable STARTTLS to upgrade insecure SMTP connections using TLS. Ignored if `CODER_NOTIFICATIONS_EMAIL_FORCE_TLS` is set. | false | -| - | `--notifications-email-tls-skip-verify` | `CODER_NOTIFICATIONS_EMAIL_TLS_SKIPVERIFY` | `bool` | Skip verification of the target server's certificate (**insecure**). | false | -| - | `--notifications-email-tls-server-name` | `CODER_NOTIFICATIONS_EMAIL_TLS_SERVERNAME` | `string` | Server name to verify against the target certificate. | | -| - | `--notifications-email-tls-cert-file` | `CODER_NOTIFICATIONS_EMAIL_TLS_CERTFILE` | `string` | Certificate file to use. | | -| - | `--notifications-email-tls-cert-key-file` | `CODER_NOTIFICATIONS_EMAIL_TLS_CERTKEYFILE` | `string` | Certificate key file to use. | | +| Required | CLI | Env | Type | Description | Default | +| :------: | --------------------------- | ----------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| - | `--email-force-tls` | `CODER_EMAIL_FORCE_TLS` | `bool` | Force a TLS connection to the configured SMTP smarthost. If port 465 is used, TLS will be forced. See https://datatracker.ietf.org/doc/html/rfc8314#section-3.3. | false | +| - | `--email-tls-starttls` | `CODER_EMAIL_TLS_STARTTLS` | `bool` | Enable STARTTLS to upgrade insecure SMTP connections using TLS. Ignored if `CODER_NOTIFICATIONS_EMAIL_FORCE_TLS` is set. | false | +| - | `--email-tls-skip-verify` | `CODER_EMAIL_TLS_SKIPVERIFY` | `bool` | Skip verification of the target server's certificate (**insecure**). | false | +| - | `--email-tls-server-name` | `CODER_EMAIL_TLS_SERVERNAME` | `string` | Server name to verify against the target certificate. | | +| - | `--email-tls-cert-file` | `CODER_EMAIL_TLS_CERTFILE` | `string` | Certificate file to use. | | +| - | `--email-tls-cert-key-file` | `CODER_EMAIL_TLS_CERTKEYFILE` | `string` | Certificate key file to use. | | -**NOTE:** you _MUST_ use `CODER_NOTIFICATIONS_EMAIL_FORCE_TLS` if your smarthost -supports TLS on a port other than `465`. +**NOTE:** you _MUST_ use `CODER_EMAIL_FORCE_TLS` if your smarthost supports TLS +on a port other than `465`. ### Send emails using G-Suite @@ -126,9 +126,9 @@ After setting the required fields above: account you wish to send from 2. Set the following configuration options: ``` - CODER_NOTIFICATIONS_EMAIL_SMARTHOST=smtp.gmail.com:465 - CODER_NOTIFICATIONS_EMAIL_AUTH_USERNAME=@ - CODER_NOTIFICATIONS_EMAIL_AUTH_PASSWORD="" + CODER_EMAIL_SMARTHOST=smtp.gmail.com:465 + CODER_EMAIL_AUTH_USERNAME=@ + CODER_EMAIL_AUTH_PASSWORD="" ``` See @@ -142,10 +142,10 @@ After setting the required fields above: 1. Setup an account on Microsoft 365 or outlook.com 2. Set the following configuration options: ``` - CODER_NOTIFICATIONS_EMAIL_SMARTHOST=smtp-mail.outlook.com:587 - CODER_NOTIFICATIONS_EMAIL_TLS_STARTTLS=true - CODER_NOTIFICATIONS_EMAIL_AUTH_USERNAME=@ - CODER_NOTIFICATIONS_EMAIL_AUTH_PASSWORD="" + CODER_EMAIL_SMARTHOST=smtp-mail.outlook.com:587 + CODER_EMAIL_TLS_STARTTLS=true + CODER_EMAIL_AUTH_USERNAME=@ + CODER_EMAIL_AUTH_PASSWORD="" ``` See diff --git a/docs/reference/cli/server.md b/docs/reference/cli/server.md index 981c2419cf903..42ef7f7418b45 100644 --- a/docs/reference/cli/server.md +++ b/docs/reference/cli/server.md @@ -1249,6 +1249,148 @@ Refresh interval for healthchecks. The threshold for the database health check. If the median latency of the database exceeds this threshold over 5 attempts, the database is considered unhealthy. The default value is 15ms. +### --email-from + +| | | +| ----------- | ------------------------------ | +| Type | string | +| Environment | $CODER_EMAIL_FROM | +| YAML | email.from | + +The sender's address to use. + +### --email-smarthost + +| | | +| ----------- | ----------------------------------- | +| Type | host:port | +| Environment | $CODER_EMAIL_SMARTHOST | +| YAML | email.smarthost | +| Default | localhost:587 | + +The intermediary SMTP host through which emails are sent. + +### --email-hello + +| | | +| ----------- | ------------------------------- | +| Type | string | +| Environment | $CODER_EMAIL_HELLO | +| YAML | email.hello | +| Default | localhost | + +The hostname identifying the SMTP server. + +### --email-force-tls + +| | | +| ----------- | ----------------------------------- | +| Type | bool | +| Environment | $CODER_EMAIL_FORCE_TLS | +| YAML | email.forceTLS | +| Default | false | + +Force a TLS connection to the configured SMTP smarthost. + +### --email-auth-identity + +| | | +| ----------- | --------------------------------------- | +| Type | string | +| Environment | $CODER_EMAIL_AUTH_IDENTITY | +| YAML | email.emailAuth.identity | + +Identity to use with PLAIN authentication. + +### --email-auth-username + +| | | +| ----------- | --------------------------------------- | +| Type | string | +| Environment | $CODER_EMAIL_AUTH_USERNAME | +| YAML | email.emailAuth.username | + +Username to use with PLAIN/LOGIN authentication. + +### --email-auth-password + +| | | +| ----------- | --------------------------------------- | +| Type | string | +| Environment | $CODER_EMAIL_AUTH_PASSWORD | + +Password to use with PLAIN/LOGIN authentication. + +### --email-auth-password-file + +| | | +| ----------- | -------------------------------------------- | +| Type | string | +| Environment | $CODER_EMAIL_AUTH_PASSWORD_FILE | +| YAML | email.emailAuth.passwordFile | + +File from which to load password for use with PLAIN/LOGIN authentication. + +### --email-tls-starttls + +| | | +| ----------- | -------------------------------------- | +| Type | bool | +| Environment | $CODER_EMAIL_TLS_STARTTLS | +| YAML | email.emailTLS.startTLS | + +Enable STARTTLS to upgrade insecure SMTP connections using TLS. + +### --email-tls-server-name + +| | | +| ----------- | ---------------------------------------- | +| Type | string | +| Environment | $CODER_EMAIL_TLS_SERVERNAME | +| YAML | email.emailTLS.serverName | + +Server name to verify against the target certificate. + +### --email-tls-skip-verify + +| | | +| ----------- | ---------------------------------------------- | +| Type | bool | +| Environment | $CODER_EMAIL_TLS_SKIPVERIFY | +| YAML | email.emailTLS.insecureSkipVerify | + +Skip verification of the target server's certificate (insecure). + +### --email-tls-ca-cert-file + +| | | +| ----------- | ---------------------------------------- | +| Type | string | +| Environment | $CODER_EMAIL_TLS_CACERTFILE | +| YAML | email.emailTLS.caCertFile | + +CA certificate file to use. + +### --email-tls-cert-file + +| | | +| ----------- | -------------------------------------- | +| Type | string | +| Environment | $CODER_EMAIL_TLS_CERTFILE | +| YAML | email.emailTLS.certFile | + +Certificate file to use. + +### --email-tls-cert-key-file + +| | | +| ----------- | ----------------------------------------- | +| Type | string | +| Environment | $CODER_EMAIL_TLS_CERTKEYFILE | +| YAML | email.emailTLS.certKeyFile | + +Certificate key file to use. + ### --notifications-method | | | @@ -1288,7 +1430,6 @@ The sender's address to use. | Type | host:port | | Environment | $CODER_NOTIFICATIONS_EMAIL_SMARTHOST | | YAML | notifications.email.smarthost | -| Default | localhost:587 | The intermediary SMTP host through which emails are sent. @@ -1299,7 +1440,6 @@ The intermediary SMTP host through which emails are sent. | Type | string | | Environment | $CODER_NOTIFICATIONS_EMAIL_HELLO | | YAML | notifications.email.hello | -| Default | localhost | The hostname identifying the SMTP server. @@ -1310,7 +1450,6 @@ The hostname identifying the SMTP server. | Type | bool | | Environment | $CODER_NOTIFICATIONS_EMAIL_FORCE_TLS | | YAML | notifications.email.forceTLS | -| Default | false | Force a TLS connection to the configured SMTP smarthost. diff --git a/enterprise/cli/testdata/coder_server_--help.golden b/enterprise/cli/testdata/coder_server_--help.golden index b637a0da3f74d..a6398586fa972 100644 --- a/enterprise/cli/testdata/coder_server_--help.golden +++ b/enterprise/cli/testdata/coder_server_--help.golden @@ -107,6 +107,58 @@ Use a YAML configuration file when your server launch become unwieldy. Write out the current server config as YAML to stdout. +EMAIL OPTIONS: +Configure how emails are sent. + + --email-force-tls bool, $CODER_EMAIL_FORCE_TLS (default: false) + Force a TLS connection to the configured SMTP smarthost. + + --email-from string, $CODER_EMAIL_FROM + The sender's address to use. + + --email-hello string, $CODER_EMAIL_HELLO (default: localhost) + The hostname identifying the SMTP server. + + --email-smarthost host:port, $CODER_EMAIL_SMARTHOST (default: localhost:587) + The intermediary SMTP host through which emails are sent. + +EMAIL / EMAIL AUTHENTICATION OPTIONS: +Configure SMTP authentication options. + + --email-auth-identity string, $CODER_EMAIL_AUTH_IDENTITY + Identity to use with PLAIN authentication. + + --email-auth-password string, $CODER_EMAIL_AUTH_PASSWORD + Password to use with PLAIN/LOGIN authentication. + + --email-auth-password-file string, $CODER_EMAIL_AUTH_PASSWORD_FILE + File from which to load password for use with PLAIN/LOGIN + authentication. + + --email-auth-username string, $CODER_EMAIL_AUTH_USERNAME + Username to use with PLAIN/LOGIN authentication. + +EMAIL / EMAIL TLS OPTIONS: +Configure TLS for your SMTP server target. + + --email-tls-ca-cert-file string, $CODER_EMAIL_TLS_CACERTFILE + CA certificate file to use. + + --email-tls-cert-file string, $CODER_EMAIL_TLS_CERTFILE + Certificate file to use. + + --email-tls-cert-key-file string, $CODER_EMAIL_TLS_CERTKEYFILE + Certificate key file to use. + + --email-tls-server-name string, $CODER_EMAIL_TLS_SERVERNAME + Server name to verify against the target certificate. + + --email-tls-skip-verify bool, $CODER_EMAIL_TLS_SKIPVERIFY + Skip verification of the target server's certificate (insecure). + + --email-tls-starttls bool, $CODER_EMAIL_TLS_STARTTLS + Enable STARTTLS to upgrade insecure SMTP connections using TLS. + INTROSPECTION / HEALTH CHECK OPTIONS: --health-check-refresh duration, $CODER_HEALTH_CHECK_REFRESH (default: 10m0s) Refresh interval for healthchecks. @@ -350,54 +402,68 @@ Configure how notifications are processed and delivered. NOTIFICATIONS / EMAIL OPTIONS: Configure how email notifications are sent. - --notifications-email-force-tls bool, $CODER_NOTIFICATIONS_EMAIL_FORCE_TLS (default: false) + --notifications-email-force-tls bool, $CODER_NOTIFICATIONS_EMAIL_FORCE_TLS Force a TLS connection to the configured SMTP smarthost. + DEPRECATED: Use --email-force-tls instead. --notifications-email-from string, $CODER_NOTIFICATIONS_EMAIL_FROM The sender's address to use. + DEPRECATED: Use --email-from instead. - --notifications-email-hello string, $CODER_NOTIFICATIONS_EMAIL_HELLO (default: localhost) + --notifications-email-hello string, $CODER_NOTIFICATIONS_EMAIL_HELLO The hostname identifying the SMTP server. + DEPRECATED: Use --email-hello instead. - --notifications-email-smarthost host:port, $CODER_NOTIFICATIONS_EMAIL_SMARTHOST (default: localhost:587) + --notifications-email-smarthost host:port, $CODER_NOTIFICATIONS_EMAIL_SMARTHOST The intermediary SMTP host through which emails are sent. + DEPRECATED: Use --email-smarthost instead. NOTIFICATIONS / EMAIL / EMAIL AUTHENTICATION OPTIONS: Configure SMTP authentication options. --notifications-email-auth-identity string, $CODER_NOTIFICATIONS_EMAIL_AUTH_IDENTITY Identity to use with PLAIN authentication. + DEPRECATED: Use --email-auth-identity instead. --notifications-email-auth-password string, $CODER_NOTIFICATIONS_EMAIL_AUTH_PASSWORD Password to use with PLAIN/LOGIN authentication. + DEPRECATED: Use --email-auth-password instead. --notifications-email-auth-password-file string, $CODER_NOTIFICATIONS_EMAIL_AUTH_PASSWORD_FILE File from which to load password for use with PLAIN/LOGIN authentication. + DEPRECATED: Use --email-auth-password-file instead. --notifications-email-auth-username string, $CODER_NOTIFICATIONS_EMAIL_AUTH_USERNAME Username to use with PLAIN/LOGIN authentication. + DEPRECATED: Use --email-auth-username instead. NOTIFICATIONS / EMAIL / EMAIL TLS OPTIONS: Configure TLS for your SMTP server target. --notifications-email-tls-ca-cert-file string, $CODER_NOTIFICATIONS_EMAIL_TLS_CACERTFILE CA certificate file to use. + DEPRECATED: Use --email-tls-ca-cert-file instead. --notifications-email-tls-cert-file string, $CODER_NOTIFICATIONS_EMAIL_TLS_CERTFILE Certificate file to use. + DEPRECATED: Use --email-tls-cert-file instead. --notifications-email-tls-cert-key-file string, $CODER_NOTIFICATIONS_EMAIL_TLS_CERTKEYFILE Certificate key file to use. + DEPRECATED: Use --email-tls-cert-key-file instead. --notifications-email-tls-server-name string, $CODER_NOTIFICATIONS_EMAIL_TLS_SERVERNAME Server name to verify against the target certificate. + DEPRECATED: Use --email-tls-server-name instead. --notifications-email-tls-skip-verify bool, $CODER_NOTIFICATIONS_EMAIL_TLS_SKIPVERIFY Skip verification of the target server's certificate (insecure). + DEPRECATED: Use --email-tls-skip-verify instead. --notifications-email-tls-starttls bool, $CODER_NOTIFICATIONS_EMAIL_TLS_STARTTLS Enable STARTTLS to upgrade insecure SMTP connections using TLS. + DEPRECATED: Use --email-tls-starttls instead. NOTIFICATIONS / WEBHOOK OPTIONS: --notifications-webhook-endpoint url, $CODER_NOTIFICATIONS_WEBHOOK_ENDPOINT