mirror of
https://github.com/coder/coder.git
synced 2025-07-09 11:45:56 +00:00
* feat: oidc user role sync User roles come from oidc claims. Prevent manual user role changes if set. * allow mapping 1:many
441 lines
21 KiB
Plaintext
441 lines
21 KiB
Plaintext
Usage: coder server [flags]
|
||
|
||
Start a Coder server
|
||
|
||
[1mSubcommands[0m
|
||
create-admin-user Create a new admin user with the given username,
|
||
email and password and adds it to every
|
||
organization.
|
||
postgres-builtin-serve Run the built-in PostgreSQL deployment.
|
||
postgres-builtin-url Output the connection URL for the built-in
|
||
PostgreSQL deployment.
|
||
|
||
[1mOptions[0m
|
||
--cache-dir string, $CODER_CACHE_DIRECTORY (default: [cache dir])
|
||
The directory to cache temporary files. If unspecified and
|
||
$CACHE_DIRECTORY is set, it will be used for compatibility with
|
||
systemd.
|
||
|
||
--disable-owner-workspace-access bool, $CODER_DISABLE_OWNER_WORKSPACE_ACCESS
|
||
Remove the permission for the 'owner' role to have workspace execution
|
||
on all workspaces. This prevents the 'owner' from ssh, apps, and
|
||
terminal access based on the 'owner' role. They still have their user
|
||
permissions to access their own workspaces.
|
||
|
||
--disable-path-apps bool, $CODER_DISABLE_PATH_APPS
|
||
Disable workspace apps that are not served from subdomains. Path-based
|
||
apps can make requests to the Coder API and pose a security risk when
|
||
the workspace serves malicious JavaScript. This is recommended for
|
||
security purposes if a --wildcard-access-url is configured.
|
||
|
||
--swagger-enable bool, $CODER_SWAGGER_ENABLE
|
||
Expose the swagger endpoint via /swagger.
|
||
|
||
--experiments string-array, $CODER_EXPERIMENTS
|
||
Enable one or more experiments. These are not ready for production.
|
||
Separate multiple experiments with commas, or enter '*' to opt-in to
|
||
all available experiments.
|
||
|
||
--postgres-url string, $CODER_PG_CONNECTION_URL
|
||
URL of a PostgreSQL database. If empty, PostgreSQL binaries will be
|
||
downloaded from Maven (https://repo1.maven.org/maven2) and store all
|
||
data in the config root. Access the built-in database with "coder
|
||
server postgres-builtin-url".
|
||
|
||
--ssh-keygen-algorithm string, $CODER_SSH_KEYGEN_ALGORITHM (default: ed25519)
|
||
The algorithm to use for generating ssh keys. Accepted values are
|
||
"ed25519", "ecdsa", or "rsa4096".
|
||
|
||
--update-check bool, $CODER_UPDATE_CHECK (default: false)
|
||
Periodically check for new releases of Coder and inform the owner. The
|
||
check is performed once per day.
|
||
|
||
[1mClient Options[0m
|
||
These options change the behavior of how clients interact with the Coder.
|
||
Clients include the coder cli, vs code extension, and the web UI.
|
||
|
||
--ssh-config-options string-array, $CODER_SSH_CONFIG_OPTIONS
|
||
These SSH config options will override the default SSH config options.
|
||
Provide options in "key=value" or "key value" format separated by
|
||
commas.Using this incorrectly can break SSH to your deployment, use
|
||
cautiously.
|
||
|
||
--ssh-hostname-prefix string, $CODER_SSH_HOSTNAME_PREFIX (default: coder.)
|
||
The SSH deployment prefix is used in the Host of the ssh config.
|
||
|
||
[1mConfig Options[0m
|
||
Use a YAML configuration file when your server launch become unwieldy.
|
||
|
||
-c, --config yaml-config-path, $CODER_CONFIG_PATH
|
||
Specify a YAML file to load configuration from.
|
||
|
||
--write-config bool
|
||
|
||
Write out the current server config as YAML to stdout.
|
||
|
||
[1mIntrospection / Logging Options[0m
|
||
--enable-terraform-debug-mode bool, $CODER_ENABLE_TERRAFORM_DEBUG_MODE (default: false)
|
||
Allow administrators to enable Terraform debug output.
|
||
|
||
--log-human string, $CODER_LOGGING_HUMAN (default: /dev/stderr)
|
||
Output human-readable logs to a given file.
|
||
|
||
--log-json string, $CODER_LOGGING_JSON
|
||
Output JSON logs to a given file.
|
||
|
||
--log-stackdriver string, $CODER_LOGGING_STACKDRIVER
|
||
Output Stackdriver compatible logs to a given file.
|
||
|
||
-v, --verbose bool, $CODER_VERBOSE
|
||
Output debug-level logs.
|
||
|
||
[1mIntrospection / Prometheus Options[0m
|
||
--prometheus-address host:port, $CODER_PROMETHEUS_ADDRESS (default: 127.0.0.1:2112)
|
||
The bind address to serve prometheus metrics.
|
||
|
||
--prometheus-collect-agent-stats bool, $CODER_PROMETHEUS_COLLECT_AGENT_STATS
|
||
Collect agent stats (may increase charges for metrics storage).
|
||
|
||
--prometheus-collect-db-metrics bool, $CODER_PROMETHEUS_COLLECT_DB_METRICS (default: false)
|
||
Collect database metrics (may increase charges for metrics storage).
|
||
|
||
--prometheus-enable bool, $CODER_PROMETHEUS_ENABLE
|
||
Serve prometheus metrics on the address defined by prometheus address.
|
||
|
||
[1mIntrospection / Tracing Options[0m
|
||
--trace-logs bool, $CODER_TRACE_LOGS
|
||
Enables capturing of logs as events in traces. This is useful for
|
||
debugging, but may result in a very large amount of events being sent
|
||
to the tracing backend which may incur significant costs. If the
|
||
verbose flag was supplied, debug-level logs will be included.
|
||
|
||
--trace bool, $CODER_TRACE_ENABLE
|
||
Whether application tracing data is collected. It exports to a backend
|
||
configured by environment variables. See:
|
||
https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md.
|
||
|
||
--trace-honeycomb-api-key string, $CODER_TRACE_HONEYCOMB_API_KEY
|
||
Enables trace exporting to Honeycomb.io using the provided API Key.
|
||
|
||
[1mIntrospection / pprof Options[0m
|
||
--pprof-address host:port, $CODER_PPROF_ADDRESS (default: 127.0.0.1:6060)
|
||
The bind address to serve pprof.
|
||
|
||
--pprof-enable bool, $CODER_PPROF_ENABLE
|
||
Serve pprof metrics on the address defined by pprof address.
|
||
|
||
[1mNetworking Options[0m
|
||
--access-url url, $CODER_ACCESS_URL
|
||
The URL that users will use to access the Coder deployment.
|
||
|
||
--docs-url url, $CODER_DOCS_URL
|
||
Specifies the custom docs URL.
|
||
|
||
--proxy-trusted-headers string-array, $CODER_PROXY_TRUSTED_HEADERS
|
||
Headers to trust for forwarding IP addresses. e.g. Cf-Connecting-Ip,
|
||
True-Client-Ip, X-Forwarded-For.
|
||
|
||
--proxy-trusted-origins string-array, $CODER_PROXY_TRUSTED_ORIGINS
|
||
Origin addresses to respect "proxy-trusted-headers". e.g.
|
||
192.168.1.0/24.
|
||
|
||
--redirect-to-access-url bool, $CODER_REDIRECT_TO_ACCESS_URL
|
||
Specifies whether to redirect requests that do not match the access
|
||
URL host.
|
||
|
||
--secure-auth-cookie bool, $CODER_SECURE_AUTH_COOKIE
|
||
Controls if the 'Secure' property is set on browser session cookies.
|
||
|
||
--wildcard-access-url url, $CODER_WILDCARD_ACCESS_URL
|
||
Specifies the wildcard hostname to use for workspace applications in
|
||
the form "*.example.com".
|
||
|
||
[1mNetworking / DERP Options[0m
|
||
Most Coder deployments never have to think about DERP because all connections
|
||
between workspaces and users are peer-to-peer. However, when Coder cannot
|
||
establish a peer to peer connection, Coder uses a distributed relay network
|
||
backed by Tailscale and WireGuard.
|
||
|
||
--block-direct-connections bool, $CODER_BLOCK_DIRECT
|
||
Block peer-to-peer (aka. direct) workspace connections. All workspace
|
||
connections from the CLI will be proxied through Coder (or custom
|
||
configured DERP servers) and will never be peer-to-peer when enabled.
|
||
Workspaces may still reach out to STUN servers to get their address
|
||
until they are restarted after this change has been made, but new
|
||
connections will still be proxied regardless.
|
||
|
||
--derp-config-path string, $CODER_DERP_CONFIG_PATH
|
||
Path to read a DERP mapping from. See:
|
||
https://tailscale.com/kb/1118/custom-derp-servers/.
|
||
|
||
--derp-config-url string, $CODER_DERP_CONFIG_URL
|
||
URL to fetch a DERP mapping on startup. See:
|
||
https://tailscale.com/kb/1118/custom-derp-servers/.
|
||
|
||
--derp-server-enable bool, $CODER_DERP_SERVER_ENABLE (default: true)
|
||
Whether to enable or disable the embedded DERP relay server.
|
||
|
||
--derp-server-region-code string, $CODER_DERP_SERVER_REGION_CODE (default: coder)
|
||
Region code to use for the embedded DERP server.
|
||
|
||
--derp-server-region-id int, $CODER_DERP_SERVER_REGION_ID (default: 999)
|
||
Region ID to use for the embedded DERP server.
|
||
|
||
--derp-server-region-name string, $CODER_DERP_SERVER_REGION_NAME (default: Coder Embedded Relay)
|
||
Region name that for the embedded DERP server.
|
||
|
||
--derp-server-stun-addresses string-array, $CODER_DERP_SERVER_STUN_ADDRESSES (default: stun.l.google.com:19302)
|
||
Addresses for STUN servers to establish P2P connections. Use special
|
||
value 'disable' to turn off STUN.
|
||
|
||
[1mNetworking / HTTP Options[0m
|
||
--disable-password-auth bool, $CODER_DISABLE_PASSWORD_AUTH
|
||
Disable password authentication. This is recommended for security
|
||
purposes in production deployments that rely on an identity provider.
|
||
Any user with the owner role will be able to sign in with their
|
||
password regardless of this setting to avoid potential lock out. If
|
||
you are locked out of your account, you can use the `coder server
|
||
create-admin` command to create a new admin user directly in the
|
||
database.
|
||
|
||
--disable-session-expiry-refresh bool, $CODER_DISABLE_SESSION_EXPIRY_REFRESH
|
||
Disable automatic session expiry bumping due to activity. This forces
|
||
all sessions to become invalid after the session expiry duration has
|
||
been reached.
|
||
|
||
--http-address string, $CODER_HTTP_ADDRESS (default: 127.0.0.1:3000)
|
||
HTTP bind address of the server. Unset to disable the HTTP endpoint.
|
||
|
||
--max-token-lifetime duration, $CODER_MAX_TOKEN_LIFETIME (default: 876600h0m0s)
|
||
The maximum lifetime duration users can specify when creating an API
|
||
token.
|
||
|
||
--proxy-health-interval duration, $CODER_PROXY_HEALTH_INTERVAL (default: 1m0s)
|
||
The interval in which coderd should be checking the status of
|
||
workspace proxies.
|
||
|
||
--session-duration duration, $CODER_SESSION_DURATION (default: 24h0m0s)
|
||
The token expiry duration for browser sessions. Sessions may last
|
||
longer if they are actively making requests, but this functionality
|
||
can be disabled via --disable-session-expiry-refresh.
|
||
|
||
[1mNetworking / TLS Options[0m
|
||
Configure TLS / HTTPS for your Coder deployment. If you're running Coder behind
|
||
a TLS-terminating reverse proxy or are accessing Coder over a secure link, you
|
||
can safely ignore these settings.
|
||
|
||
--strict-transport-security int, $CODER_STRICT_TRANSPORT_SECURITY (default: 0)
|
||
Controls if the 'Strict-Transport-Security' header is set on all
|
||
static file responses. This header should only be set if the server is
|
||
accessed via HTTPS. This value is the MaxAge in seconds of the header.
|
||
|
||
--strict-transport-security-options string-array, $CODER_STRICT_TRANSPORT_SECURITY_OPTIONS
|
||
Two optional fields can be set in the Strict-Transport-Security
|
||
header; 'includeSubDomains' and 'preload'. The
|
||
'strict-transport-security' flag must be set to a non-zero value for
|
||
these options to be used.
|
||
|
||
--tls-address host:port, $CODER_TLS_ADDRESS (default: 127.0.0.1:3443)
|
||
HTTPS bind address of the server.
|
||
|
||
--tls-cert-file string-array, $CODER_TLS_CERT_FILE
|
||
Path to each certificate for TLS. It requires a PEM-encoded file. To
|
||
configure the listener to use a CA certificate, concatenate the
|
||
primary certificate and the CA certificate together. The primary
|
||
certificate should appear first in the combined file.
|
||
|
||
--tls-client-auth string, $CODER_TLS_CLIENT_AUTH (default: none)
|
||
Policy the server will follow for TLS Client Authentication. Accepted
|
||
values are "none", "request", "require-any", "verify-if-given", or
|
||
"require-and-verify".
|
||
|
||
--tls-client-ca-file string, $CODER_TLS_CLIENT_CA_FILE
|
||
PEM-encoded Certificate Authority file used for checking the
|
||
authenticity of client.
|
||
|
||
--tls-client-cert-file string, $CODER_TLS_CLIENT_CERT_FILE
|
||
Path to certificate for client TLS authentication. It requires a
|
||
PEM-encoded file.
|
||
|
||
--tls-client-key-file string, $CODER_TLS_CLIENT_KEY_FILE
|
||
Path to key for client TLS authentication. It requires a PEM-encoded
|
||
file.
|
||
|
||
--tls-enable bool, $CODER_TLS_ENABLE
|
||
Whether TLS will be enabled.
|
||
|
||
--tls-key-file string-array, $CODER_TLS_KEY_FILE
|
||
Paths to the private keys for each of the certificates. It requires a
|
||
PEM-encoded file.
|
||
|
||
--tls-min-version string, $CODER_TLS_MIN_VERSION (default: tls12)
|
||
Minimum supported version of TLS. Accepted values are "tls10",
|
||
"tls11", "tls12" or "tls13".
|
||
|
||
[1mOAuth2 / GitHub Options[0m
|
||
--oauth2-github-allow-everyone bool, $CODER_OAUTH2_GITHUB_ALLOW_EVERYONE
|
||
Allow all logins, setting this option means allowed orgs and teams
|
||
must be empty.
|
||
|
||
--oauth2-github-allow-signups bool, $CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS
|
||
Whether new users can sign up with GitHub.
|
||
|
||
--oauth2-github-allowed-orgs string-array, $CODER_OAUTH2_GITHUB_ALLOWED_ORGS
|
||
Organizations the user must be a member of to Login with GitHub.
|
||
|
||
--oauth2-github-allowed-teams string-array, $CODER_OAUTH2_GITHUB_ALLOWED_TEAMS
|
||
Teams inside organizations the user must be a member of to Login with
|
||
GitHub. Structured as: <organization-name>/<team-slug>.
|
||
|
||
--oauth2-github-client-id string, $CODER_OAUTH2_GITHUB_CLIENT_ID
|
||
Client ID for Login with GitHub.
|
||
|
||
--oauth2-github-client-secret string, $CODER_OAUTH2_GITHUB_CLIENT_SECRET
|
||
Client secret for Login with GitHub.
|
||
|
||
--oauth2-github-enterprise-base-url string, $CODER_OAUTH2_GITHUB_ENTERPRISE_BASE_URL
|
||
Base URL of a GitHub Enterprise deployment to use for Login with
|
||
GitHub.
|
||
|
||
[1mOIDC Options[0m
|
||
--oidc-allow-signups bool, $CODER_OIDC_ALLOW_SIGNUPS (default: true)
|
||
Whether new users can sign up with OIDC.
|
||
|
||
--oidc-auth-url-params struct[map[string]string], $CODER_OIDC_AUTH_URL_PARAMS (default: {"access_type": "offline"})
|
||
OIDC auth URL parameters to pass to the upstream provider.
|
||
|
||
--oidc-client-id string, $CODER_OIDC_CLIENT_ID
|
||
Client ID to use for Login with OIDC.
|
||
|
||
--oidc-client-secret string, $CODER_OIDC_CLIENT_SECRET
|
||
Client secret to use for Login with OIDC.
|
||
|
||
--oidc-email-domain string-array, $CODER_OIDC_EMAIL_DOMAIN
|
||
Email domains that clients logging in with OIDC must match.
|
||
|
||
--oidc-email-field string, $CODER_OIDC_EMAIL_FIELD (default: email)
|
||
OIDC claim field to use as the email.
|
||
|
||
--oidc-group-field string, $CODER_OIDC_GROUP_FIELD
|
||
This field must be set if using the group sync feature and the scope
|
||
name is not 'groups'. Set to the claim to be used for groups.
|
||
|
||
--oidc-group-mapping struct[map[string]string], $CODER_OIDC_GROUP_MAPPING (default: {})
|
||
A map of OIDC group IDs and the group in Coder it should map to. This
|
||
is useful for when OIDC providers only return group IDs.
|
||
|
||
--oidc-ignore-email-verified bool, $CODER_OIDC_IGNORE_EMAIL_VERIFIED
|
||
Ignore the email_verified claim from the upstream provider.
|
||
|
||
--oidc-ignore-userinfo bool, $CODER_OIDC_IGNORE_USERINFO (default: false)
|
||
Ignore the userinfo endpoint and only use the ID token for user
|
||
information.
|
||
|
||
--oidc-issuer-url string, $CODER_OIDC_ISSUER_URL
|
||
Issuer URL to use for Login with OIDC.
|
||
|
||
--oidc-scopes string-array, $CODER_OIDC_SCOPES (default: openid,profile,email)
|
||
Scopes to grant when authenticating with OIDC.
|
||
|
||
--oidc-user-role-default string-array, $CODER_OIDC_USER_ROLE_DEFAULT
|
||
If user role sync is enabled, these roles are always included for all
|
||
authenticated users. The 'member' role is always assigned.
|
||
|
||
--oidc-user-role-field string, $CODER_OIDC_USER_ROLE_FIELD
|
||
This field must be set if using the user roles sync feature. Set this
|
||
to the name of the claim used to store the user's role. The roles
|
||
should be sent as an array of strings.
|
||
|
||
--oidc-user-role-mapping struct[map[string][]string], $CODER_OIDC_USER_ROLE_MAPPING (default: {})
|
||
A map of the OIDC passed in user roles and the groups in Coder it
|
||
should map to. This is useful if the group names do not match. If
|
||
mapped to the empty string, the role will ignored.
|
||
|
||
--oidc-username-field string, $CODER_OIDC_USERNAME_FIELD (default: preferred_username)
|
||
OIDC claim field to use as the username.
|
||
|
||
--oidc-sign-in-text string, $CODER_OIDC_SIGN_IN_TEXT (default: OpenID Connect)
|
||
The text to show on the OpenID Connect sign in button.
|
||
|
||
--oidc-icon-url url, $CODER_OIDC_ICON_URL
|
||
URL pointing to the icon to use on the OepnID Connect login button.
|
||
|
||
[1mProvisioning Options[0m
|
||
Tune the behavior of the provisioner, which is responsible for creating,
|
||
updating, and deleting workspace resources.
|
||
|
||
--provisioner-force-cancel-interval duration, $CODER_PROVISIONER_FORCE_CANCEL_INTERVAL (default: 10m0s)
|
||
Time to force cancel provisioning tasks that are stuck.
|
||
|
||
--provisioner-daemon-poll-interval duration, $CODER_PROVISIONER_DAEMON_POLL_INTERVAL (default: 1s)
|
||
Time to wait before polling for a new job.
|
||
|
||
--provisioner-daemon-poll-jitter duration, $CODER_PROVISIONER_DAEMON_POLL_JITTER (default: 100ms)
|
||
Random jitter added to the poll interval.
|
||
|
||
--provisioner-daemons int, $CODER_PROVISIONER_DAEMONS (default: 3)
|
||
Number of provisioner daemons to create on start. If builds are stuck
|
||
in queued state for a long time, consider increasing this.
|
||
|
||
[1mTelemetry Options[0m
|
||
Telemetry is critical to our ability to improve Coder. We strip all
|
||
personalinformation before sending data to our servers. Please only disable
|
||
telemetrywhen required by your organization's security policy.
|
||
|
||
--telemetry bool, $CODER_TELEMETRY_ENABLE (default: false)
|
||
Whether telemetry is enabled or not. Coder collects anonymized usage
|
||
data to help improve our product.
|
||
|
||
--telemetry-trace bool, $CODER_TELEMETRY_TRACE (default: false)
|
||
Whether Opentelemetry traces are sent to Coder. Coder collects
|
||
anonymized application tracing to help improve our product. Disabling
|
||
telemetry also disables this option.
|
||
|
||
[1mUser Quiet Hours Schedule Options[0m
|
||
Allow users to set quiet hours schedules each day for workspaces to avoid
|
||
workspaces stopping during the day due to template max TTL.
|
||
|
||
--default-quiet-hours-schedule string, $CODER_QUIET_HOURS_DEFAULT_SCHEDULE
|
||
The default daily cron schedule applied to users that haven't set a
|
||
custom quiet hours schedule themselves. The quiet hours schedule
|
||
determines when workspaces will be force stopped due to the template's
|
||
max TTL, and will round the max TTL up to be within the user's quiet
|
||
hours window (or default). The format is the same as the standard cron
|
||
format, but the day-of-month, month and day-of-week must be *. Only
|
||
one hour and minute can be specified (ranges or comma separated values
|
||
are not supported).
|
||
|
||
[1m⚠️ Dangerous Options[0m
|
||
--dangerous-allow-path-app-sharing bool, $CODER_DANGEROUS_ALLOW_PATH_APP_SHARING
|
||
Allow workspace apps that are not served from subdomains to be shared.
|
||
Path-based app sharing is DISABLED by default for security purposes.
|
||
Path-based apps can make requests to the Coder API and pose a security
|
||
risk when the workspace serves malicious JavaScript. Path-based apps
|
||
can be disabled entirely with --disable-path-apps for further
|
||
security.
|
||
|
||
--dangerous-allow-path-app-site-owner-access bool, $CODER_DANGEROUS_ALLOW_PATH_APP_SITE_OWNER_ACCESS
|
||
Allow site-owners to access workspace apps from workspaces they do not
|
||
own. Owners cannot access path-based apps they do not own by default.
|
||
Path-based apps can make requests to the Coder API and pose a security
|
||
risk when the workspace serves malicious JavaScript. Path-based apps
|
||
can be disabled entirely with --disable-path-apps for further
|
||
security.
|
||
|
||
[1mEnterprise Options[0m
|
||
These options are only available in the Enterprise Edition.
|
||
|
||
--browser-only bool, $CODER_BROWSER_ONLY
|
||
Whether Coder only allows connections to workspaces via the browser.
|
||
|
||
--derp-server-relay-url url, $CODER_DERP_SERVER_RELAY_URL
|
||
An HTTP URL that is accessible by other replicas to relay DERP
|
||
traffic. Required for high availability.
|
||
|
||
--scim-auth-header string, $CODER_SCIM_AUTH_HEADER
|
||
Enables SCIM and sets the authentication header for the built-in SCIM
|
||
server. New users are automatically created with OIDC authentication.
|
||
|
||
---
|
||
Run `coder --help` for a list of global options.
|