Config Options {#RefConfigOptions}

Fragment.

This page is about the yaml files that determine the configuration of the Wire backend services.

Settings in galley

# [galley.yaml]
settings:
  enableIndexedBillingTeamMembers: false

Indexed Billing Team Members

Use indexed billing team members for journaling. When enabled, galley would use the billing_team_member table to send billing events with user ids of team owners (who have the SetBilling permission). Before enabling this flag, the billing_team_member table must be backfilled.

Even when the flag is disabled, galley will keep writing to the biling_team_member table, this flag only affects the reads and has been added in order to deploy new code and backfill data in production.

Feature flags

Feature flags can be used to turn features on or off, or determine the behavior of the features. Example:

# [galley.yaml]
settings:
  featureFlags:
    sso: disabled-by-default
    legalhold: disabled-by-default
    teamSearchVisibility: disabled-by-default
    setEmailVisibility: visible_to_self

The featureFlags field in the galley settings is mandatory, and all features must be listed. Each feature defines its own set of allowed flag values. (The reason for that is that as we will see, the semantics is slightly different (or more specific) than boolean.)

SSO

This sets the default setting for all teams, and can be overridden by customer support / backoffice. Allowed values: disabled-by-default, enabled-by-default.

IMPORTANT: if you change this from 'enabled-by-default' to 'disabled-by-default' in production, you need to run this migration script to fix all teams that have registered an idp. (if you don't, the idp will keep working, but the admin won't be able to register new idps.)

LegalHold

Optionally block customer support / backoffice from enabling legal hold for individual teams. Allowed values: 'disabled-permanently', 'disabled-by-default'.

IMPORTANT: If you switch this back to disabled-permanently from disabled-by-default, LegalHold devices may still be active in teams that have created them while it was allowed. This may change in the future.

Team Search Visibility

Is a team allowed to change its team search visibility settings? If enabled for the team, it can be configured so that non-team users do not show up in search.

This sets the default setting for all teams, and can be overridden for individual teams by customer support / backoffice. Allowed values: disabled-by-default, enabled-by-default.

Disabled by default in the wire cloud.

Backoffice hook looks like this:

GET /teams/{tid}/search-visibility
  -- Shows the current TeamSearchVisibility value for the given team

PUT /teams/{tid}/search-visibility
  -- Set specific search visibility for the team

pull-down-menu "body":
  "standard"
  "no-name-outside-team"

Email Visibility

Allowd values and their description.

Classified domains

To enable classified domains, the following needs to be in galley.yaml or wire-server/values.yaml under settings / featureFlags:

classifiedDomains:
  status: enabled
  config:
    domains: ["example.com", "example2.com"]

Note that when enabling this feature, it is important to provide your own domain too in the list of domains. In the example above, example.com or example2.com is your domain.

To disable, either omit the entry entirely (it is disabled by default), or provide the following:

classifiedDomains:
  status: disabled
  config:
    domains: []

Conference Calling

The conferenceCalling feature flag controls whether a user can initiate a conference call. The flag can be toggled between its states enabled and disabled per team via an internal endpoint.

The conferenceCalling section in featureFlags defines the state of the conferenceCalling feature flag for all personal users (users that don't belong to a team). For personal users there is no way to toggle the flag, so the setting of the config section wholly defines the state of conferenceCalling flag for all personal users.

The conferenceCalling section in featureFlags also defines the initial state of the conferenceCalling flag for all teams. After the flag is set for the first time for a team via the internal endpoint the value from the config section will be ignored.

Example value for the config section:

conferenceCalling:
  defaults:
    status: enabled

The conferenceCalling section is optional in featureFlags. If it is omitted then it is assumed to be enabled.

See also: conference falling for personal accounts (below).

File Sharing

File sharing is enabled and unlocked by default. If you want a different configuration, use the following syntax:

fileSharing:
  defaults:
    status: disabled|enabled
    lockStatus: locked|unlocked

These are all the possible combinations of status and lockStatus:

`status`	`lockStatus`
`enabled`	`locked`	Feature enabled, cannot be disabled by team admin
`enabled`	`unlocked`	Feature enabled, can be disabled by team admin
`disabled`	`locked`	Feature disabled, cannot be enabled by team admin
`disabled`	`unlocked`	Feature disabled, can be enabled by team admin

The lock status for individual teams can be changed via the internal API (PUT /i/teams/:tid/features/fileSharing/(un)?locked).

The feature status for individual teams can be changed via the public API (if the feature is unlocked).

Validate SAML Emails

If this is enabled, if a new user account is created with an email address as SAML NameID or SCIM externalId, users will receive a validation email. If they follow the validation procedure, they will be able to receive emails about their account, eg., if a new device is associated with the account. If the user does not validate their email address, they can still use it to login.

Validate SAML emails is enabled by default; this is almost always what you want. If you want a different configuration, use the following syntax:

# galley.yaml
validateSAMLEmails:
  defaults:
    status: disabled

2nd Factor Password Challenge

By default Wire enforces a 2nd factor authentication for certain user operations like e.g. activating an account, changing email or password, or deleting an account. If this feature is enabled, a 2nd factor password challenge will be performed for a set of additional user operations like e.g. for generating SCIM tokens, login, or adding a client.

Usually the default is what you want. If you explicitly want to enable the feature, use the following syntax:

# galley.yaml
sndFactorPasswordChallenge:
  defaults:
    status: disabled|enabled
    lockStatus: locked|unlocked

Federation Domain

Regardless of whether a backend wants to enable federation or not, the operator must decide what its domain is going to be. This helps in keeping things simpler across all components of Wire and also enables to turn on federation in the future if required.

For production uses, it is highly recommended that this domain be configured as something that is controlled by the operator(s). The backend or frontend do not need to be available on this domain. As per our current federation design, you must be able to set an SRV record for _wire-server-federator._tcp.<domain>. This record should have entries which lead to the federator.

IMPORTANT Once this option is set, it cannot be changed without breaking experience for all the users which are already using the backend.

This configuration needs to be made in brig, cargohold and galley (note the slighly different spelling of the config options).

# brig.yaml
optSettings:
  setFederationDomain: example.com

# cargohold.yaml
settings:
  federationDomain: example.com

# galley.yaml
settings:
  federationDomain: example.com

Federation allow list

As of 2021-07, federation (whatever is implemented by the time you read this) is turned off by default by means of having an empty allow list:

# federator.yaml
optSettings:
  federationStrategy:
    allowedDomains: []

You can choose to federate with a specific list of allowed servers:

# federator.yaml
optSettings:
  federationStrategy:
    allowedDomains:
      - server1.example.com
      - server2.example.com

or, you can federate with everyone:

# federator.yaml
optSettings:
  federationStrategy:
    # note the 'empty' value after 'allowAll'
    allowAll:

# when configuring helm charts, this becomes (note 'true' after 'allowAll')
# inside helm_vars/wire-server:
federator:
  optSettings:
    federationStrategy:
      allowAll: true

Federation TLS Config

When a federator connects with another federator, it does so over HTTPS. There are a few options to configure the CA for this:

useSystemCAStore: Boolean. If set to True it will use the system CA.
remoteCAStore: Maybe Filepath. This config option can be used to specify multiple certificates from either a single file (multiple PEM formatted certificates concatenated) or directory (one certificate per file, file names are hashes from certificate).
clientCertificate: Maybe Filepath. A client certificate to use when connecting to remote federators. If this option is omitted, no client certificate is used. If it is provided, then the clientPrivateKey option (see below) must be provided as well.
clientPrivateKey: Maybe Filepath. The private key corresponding to the clientCertificate option above. It is an error to provide only a private key without the corresponding certificate.

Both the useSystemCAStore and remoteCAStore options can be specified, in which case the stores are concatenated and used for verifying certificates. When useSystemCAStore is set to false and remoteCAStore is not provided, all outbound connections will fail with a TLS error as there will be no CA for verifying the server certificate.

Examples

Federate with anyone, no client certificates, use system CA store to verify server certificates:

federator:
  optSettings:
    federationStrategy:
      allowAll:
    useSystemCAStore: true

Federate only with server2.example.com, use a client certificate and a specific CA:

federator:
  optSettings:
    federationStrategy:
      allowedDomains:
        - server2.example.com
    useSystemCAStore: false
    clientCertificate: client.pem
    clientPrivateKey: client-key.pem

Settings in brig

Some features (as of the time of writing this: only conferenceCalling) allow to set defaults for personal accounts in brig. Those are taken into account in galley's end-points GET /feature-configs*.

To be specific:

Conference Calling

Two values can be configured for personal accounts: a default for when the user record contains null as feature config, and default that should be inserted into the user record when creating new users:

# [brig.yaml]
settings:
  setFeatureFlags:
    conferenceCalling:
      defaultForNew:
        status: disabled
      defaultForNull:
        status: enabled

You can omit the entire conferenceCalling block, but not parts of it. Built-in defaults: defaultForNew: null (user record attribute is left empty); defaultForNull: enabled. This maintains behavior prior to the introduction of this change, while allowing site owners to postpone the decision about the default setting.

When new users are created, their config will be initialized with what's in defaultForNew.

When a null value is encountered, it is assumed to be defaultForNull.

(Introduced in #1811.)

SFT configuration

Configuring SFT load balancing can be done in two (mutually exclusive) settings:

Configuring a SRV DNS record based load balancing setting

# [brig.yaml]
sft:
  sftBaseDomain: sft.wire.example.yourcloud.comk
  sftSRVServiceName: sft
  sftDiscoveryIntervalSeconds: 10
  sftListLength: 20

or

Configuring a HTTP-based load balancing setting

# [brig.yaml]
settings:
  setSftStaticUrl: https://sftd.wire.yourcloud.com

This setting assumes that the sft load balancer has been deployed witht hte sftd helm chart.

Additionally if setSftListAllServers is set to enabled (disabled by default) then the /calls/config/v2 endpoint will include a list of all servers that are load balanced by setSftStaticUrl at field sft_servers_all. This is required to enable calls between federated instances of Wire.

Locale

setDefaultLocale (deprecated / ignored)

The brig server config option setDefaultLocale has been replaced by setDefaultUserLocale and setDefaultTemplateLocale. Both settings are optional and setDefaultTemplateLocale defaults to EN and setDefaultLocale defaults to setDefaultTemplateLocale. If setDefaultLocale was not set or set to EN before this change, nothing needs to be done. If setDefaultLocale was set to any other language other than EN the name of the setting should be changed to setDefaultTemplateLocale.

`setDefaultTemplateLocale`

This option determines the default locale for email templates. The language of the email communication is determined by the user locale (see above). Only if templates of the the locale of the user do not exist or if user locale is not set the setDefaultTemplateLocale is used as a fallback. If not set the default is EN. This setting should not be changed unless a complete set of templates is available for the given language.

# [brig.yaml]
optSettings:
  setDefaultTemplateLocale: en

`setDefaultUserLocale`

This option is the default user locale to be used if it is not set in the user profile. This can be the case if the users are provisioned by SCIM e.g. This option determines which language to use for email communication. If not set the default is the value that is configured for setDefaultTemplateLocale.

# [brig.yaml]
optSettings:
  setDefaultUserLocale: en

MLS settings

`setKeyPackageMaximumLifetime`

This option specifies the maximum accepted lifetime of a key package from the moment it is uploaded, in seconds. For example, when brig is configured as follows:

# [brig.yaml]
optSettings:
  setKeyPackageMaximumLifetime: 1296000 # 15 days

any key package whose expiry date is set further than 15 days after upload time will be rejected.

Federated domain specific configuration settings

Restrict user search

The lookup and search of users on a wire instance can be configured. This can be done per federated domain.

# [brig.yaml]
optSettings:
  setFederationDomainConfigs:
    - domain: example.com
      search_policy: no_search

Valid values for search_policy are:

no_search: No users are returned by federated searches.
exact_handle_search: Only users where the handle exactly matches are returned.
full_search: Additionally to exact_handle_search, users are found by a freetext search on handle and display name.

If there is no configuration for a domain, it's defaulted to no_search.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

config-options.md

config-options.md

Config Options {#RefConfigOptions}

Settings in galley

Indexed Billing Team Members

Feature flags

SSO

LegalHold

Team Search Visibility

Email Visibility

Classified domains

Conference Calling

File Sharing

Validate SAML Emails

2nd Factor Password Challenge

Federation Domain

Federation allow list

Federation TLS Config

Examples

Settings in brig

Conference Calling

SFT configuration

Locale

setDefaultLocale (deprecated / ignored)

`setDefaultTemplateLocale`

`setDefaultUserLocale`

MLS settings

`setKeyPackageMaximumLifetime`

Federated domain specific configuration settings

Restrict user search

Files

config-options.md

Latest commit

History

config-options.md

File metadata and controls

Config Options {#RefConfigOptions}

Settings in galley

Indexed Billing Team Members

Feature flags

SSO

LegalHold

Team Search Visibility

Email Visibility

Classified domains

Conference Calling

File Sharing

Validate SAML Emails

2nd Factor Password Challenge

Federation Domain

Federation allow list

Federation TLS Config

Examples

Settings in brig

Conference Calling

SFT configuration

Locale

setDefaultLocale (deprecated / ignored)

setDefaultTemplateLocale

setDefaultUserLocale

MLS settings

setKeyPackageMaximumLifetime

Federated domain specific configuration settings

Restrict user search

`setDefaultTemplateLocale`

`setDefaultUserLocale`

`setKeyPackageMaximumLifetime`