synced/coder
1
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2025-07-15 22:20:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore(cli): drop 'notification' prefix for configuring email auth (#15270)

Browse Source 
Closes https://github.com/coder/coder/issues/14644
This commit is contained in:
Danielle Maywood
2024-10-30 10:06:10 +00:00
committed by GitHub
parent 25738388d5
commit 823a2ea22e
8 changed files with 536 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
cli/testdata/coder_server_--help.golden vendored
View File

@ -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

51
cli/testdata/server-config.yaml.golden vendored
View File

@ -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: <unset>, 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: <unset>, type: string)
identity: ""
# Username to use with PLAIN/LOGIN authentication.
# (default: <unset>, type: string)
username: ""
# File from which to load password for use with PLAIN/LOGIN authentication.
# (default: <unset>, type: string)
passwordFile: ""
# Configure TLS for your SMTP server target.
emailTLS:
# Enable STARTTLS to upgrade insecure SMTP connections using TLS.
# (default: <unset>, type: bool)
startTLS: false
# Server name to verify against the target certificate.
# (default: <unset>, type: string)
serverName: ""
# Skip verification of the target server's certificate (insecure).
# (default: <unset>, type: bool)
insecureSkipVerify: false
# CA certificate file to use.
# (default: <unset>, type: string)
caCertFile: ""
# Certificate file to use.
# (default: <unset>, type: string)
certFile: ""
# Certificate key file to use.
# (default: <unset>, 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: <unset>, type: string)
from: ""
# The intermediary SMTP host through which emails are sent.
# (default: localhost:587, type: host:port)
# (default: <unset>, type: host:port)
smarthost: localhost:587
# The hostname identifying the SMTP server.
# (default: localhost, type: string)
# (default: <unset>, type: string)
hello: localhost
# Force a TLS connection to the configured SMTP smarthost.
# (default: false, type: bool)
# (default: <unset>, type: bool)
forceTLS: false
# Configure SMTP authentication options.
emailAuth:

4
coderd/notifications/dispatch/smtp.go
View File

@ -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
}

178
codersdk/deployment.go
View File

@ -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",

3
codersdk/deployment_test.go
View File

@ -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,
},

50
docs/admin/monitoring/notifications/index.md
View File

@ -90,33 +90,33 @@ 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 |
| :------: | ------------------- | ----------------------- | ----------- | ----------------------------------------- | ------------- |
| ✔️ | `--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. |
| :------: | ---------------------------- | -------------------------------- | -------- | ------------------------------------------------------------------------- |
| - | `--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. | |
| :------: | --------------------------- | ----------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| - | `--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=<user>@<domain>
CODER_NOTIFICATIONS_EMAIL_AUTH_PASSWORD="<app password created above>"
CODER_EMAIL_SMARTHOST=smtp.gmail.com:465
CODER_EMAIL_AUTH_USERNAME=<user>@<domain>
CODER_EMAIL_AUTH_PASSWORD="<app password created above>"
```
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=<user>@<domain>
CODER_NOTIFICATIONS_EMAIL_AUTH_PASSWORD="<account password>"
CODER_EMAIL_SMARTHOST=smtp-mail.outlook.com:587
CODER_EMAIL_TLS_STARTTLS=true
CODER_EMAIL_AUTH_USERNAME=<user>@<domain>
CODER_EMAIL_AUTH_PASSWORD="<account password>"
```
See

145
docs/reference/cli/server.md generated
View File

@ -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 | <code>string</code> |
| Environment | <code>$CODER_EMAIL_FROM</code> |
| YAML | <code>email.from</code> |
The sender's address to use.
### --email-smarthost
| | |
| ----------- | ----------------------------------- |
| Type | <code>host:port</code> |
| Environment | <code>$CODER_EMAIL_SMARTHOST</code> |
| YAML | <code>email.smarthost</code> |
| Default | <code>localhost:587</code> |
The intermediary SMTP host through which emails are sent.
### --email-hello
| | |
| ----------- | ------------------------------- |
| Type | <code>string</code> |
| Environment | <code>$CODER_EMAIL_HELLO</code> |
| YAML | <code>email.hello</code> |
| Default | <code>localhost</code> |
The hostname identifying the SMTP server.
### --email-force-tls
| | |
| ----------- | ----------------------------------- |
| Type | <code>bool</code> |
| Environment | <code>$CODER_EMAIL_FORCE_TLS</code> |
| YAML | <code>email.forceTLS</code> |
| Default | <code>false</code> |
Force a TLS connection to the configured SMTP smarthost.
### --email-auth-identity
| | |
| ----------- | --------------------------------------- |
| Type | <code>string</code> |
| Environment | <code>$CODER_EMAIL_AUTH_IDENTITY</code> |
| YAML | <code>email.emailAuth.identity</code> |
Identity to use with PLAIN authentication.
### --email-auth-username
| | |
| ----------- | --------------------------------------- |
| Type | <code>string</code> |
| Environment | <code>$CODER_EMAIL_AUTH_USERNAME</code> |
| YAML | <code>email.emailAuth.username</code> |
Username to use with PLAIN/LOGIN authentication.
### --email-auth-password
| | |
| ----------- | --------------------------------------- |
| Type | <code>string</code> |
| Environment | <code>$CODER_EMAIL_AUTH_PASSWORD</code> |
Password to use with PLAIN/LOGIN authentication.
### --email-auth-password-file
| | |
| ----------- | -------------------------------------------- |
| Type | <code>string</code> |
| Environment | <code>$CODER_EMAIL_AUTH_PASSWORD_FILE</code> |
| YAML | <code>email.emailAuth.passwordFile</code> |
File from which to load password for use with PLAIN/LOGIN authentication.
### --email-tls-starttls
| | |
| ----------- | -------------------------------------- |
| Type | <code>bool</code> |
| Environment | <code>$CODER_EMAIL_TLS_STARTTLS</code> |
| YAML | <code>email.emailTLS.startTLS</code> |
Enable STARTTLS to upgrade insecure SMTP connections using TLS.
### --email-tls-server-name
| | |
| ----------- | ---------------------------------------- |
| Type | <code>string</code> |
| Environment | <code>$CODER_EMAIL_TLS_SERVERNAME</code> |
| YAML | <code>email.emailTLS.serverName</code> |
Server name to verify against the target certificate.
### --email-tls-skip-verify
| | |
| ----------- | ---------------------------------------------- |
| Type | <code>bool</code> |
| Environment | <code>$CODER_EMAIL_TLS_SKIPVERIFY</code> |
| YAML | <code>email.emailTLS.insecureSkipVerify</code> |
Skip verification of the target server's certificate (insecure).
### --email-tls-ca-cert-file
| | |
| ----------- | ---------------------------------------- |
| Type | <code>string</code> |
| Environment | <code>$CODER_EMAIL_TLS_CACERTFILE</code> |
| YAML | <code>email.emailTLS.caCertFile</code> |
CA certificate file to use.
### --email-tls-cert-file
| | |
| ----------- | -------------------------------------- |
| Type | <code>string</code> |
| Environment | <code>$CODER_EMAIL_TLS_CERTFILE</code> |
| YAML | <code>email.emailTLS.certFile</code> |
Certificate file to use.
### --email-tls-cert-key-file
| | |
| ----------- | ----------------------------------------- |
| Type | <code>string</code> |
| Environment | <code>$CODER_EMAIL_TLS_CERTKEYFILE</code> |
| YAML | <code>email.emailTLS.certKeyFile</code> |
Certificate key file to use.
### --notifications-method
| | |
@ -1288,7 +1430,6 @@ The sender's address to use.
| Type | <code>host:port</code> |
| Environment | <code>$CODER_NOTIFICATIONS_EMAIL_SMARTHOST</code> |
| YAML | <code>notifications.email.smarthost</code> |
| Default | <code>localhost:587</code> |
The intermediary SMTP host through which emails are sent.
@ -1299,7 +1440,6 @@ The intermediary SMTP host through which emails are sent.
| Type | <code>string</code> |
| Environment | <code>$CODER_NOTIFICATIONS_EMAIL_HELLO</code> |
| YAML | <code>notifications.email.hello</code> |
| Default | <code>localhost</code> |
The hostname identifying the SMTP server.
@ -1310,7 +1450,6 @@ The hostname identifying the SMTP server.
| Type | <code>bool</code> |
| Environment | <code>$CODER_NOTIFICATIONS_EMAIL_FORCE_TLS</code> |
| YAML | <code>notifications.email.forceTLS</code> |
| Default | <code>false</code> |
Force a TLS connection to the configured SMTP smarthost.

72
enterprise/cli/testdata/coder_server_--help.golden vendored
View File

@ -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