Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Build Features

The public Cargo feature surface is defined in src/main/Cargo.toml.

Cargo features

FeatureDefaultDescription
brotli_compression✔️Brotli HTTP response compression and outbound response decompression. Enable http.compression.brotli = true; the client must accept Brotli; network.http.brotli controls outbound negotiation.
bzip2_compression✔️Bzip2 compression for RocksDB. Select rocksdb.compression_algo = "bz2".
console✔️Interactive administration console on the terminal. Start with --console; an interactive terminal is needed.
cpu_affinity✔️Pin Tokio worker threads and database pool workers to CPU cores. A build without it leaves thread placement to the operating system, ignores database.pool.affinity, sizes the database pool from database.pool.workers instead of detected storage queues, and counts CPUs with the Rust standard library, which also applies cgroup CPU quotas. OpenBSD counts CPUs with num_cpus either way.
direct_tls✔️Serve HTTPS directly from Tuwunel. Configure the certificate and key in [global.tls].
element_hacks✔️Workarounds for Element: password authentication accepts the deprecated user field, and lazy-loaded syncs always include redundant members. These compatibility workarounds apply without additional runtime configuration.
email✔️Send email through an SMTP relay: verification mail for adding an address, registering and resetting a password, and notification mail for email pushers. Required when smtp.connection_uri is set; a build without it refuses to start then, so it cannot require email at registration. Otherwise such a build answers as a server without SMTP: requests to verify or add an email address are refused, the m.3pid_changes capability reads disabled, new email pushers are refused, and existing ones send nothing. Addresses bound by an identity provider, MAS provisioning, admin commands or the Synapse admin API stay bound and listed.
gcs_storage✔️Store media on Google Cloud Storage through [global.storage_provider.<ID>.gcs] providers. Supports presigned download redirects (media.allow_redirect). Required when such a section sets bucket; a build without it refuses to start then.
gzip_compression✔️Gzip HTTP response compression and outbound response decompression. Enable http.compression.gzip = true; the client must accept Gzip; network.http.gzip controls outbound negotiation.
io_uring✔️RocksDB I/O through io_uring. Requires Linux with kernel support for io_uring; liburing is needed when dynamically linked.
jemalloc✔️Use jemalloc for Tuwunel allocations. MSVC uses the system allocator; dynamically linked jemalloc builds need the allocator library.
jemalloc_conf✔️Apply Tuwunel’s built-in jemalloc tuning. The jemalloc feature must also be enabled; this feature configures the allocator but does not select it.
jemalloc_prof×Compile jemalloc heap profiling support. Enable jemalloc and profiling through the allocator’s runtime configuration; a substituted allocator must support profiling.
jemalloc_stats×Compile jemalloc allocation statistics support. Enable jemalloc; a substituted allocator must support statistics.
jwt_login✔️Authenticate with a JSON Web Token through login (org.matrix.login.jwt) or user-interactive authentication. Configure authentication in [global.jwt]. Also provides the debug create-jwt admin command. Required when jwt.enable is true. A build without this feature rejects that configuration at startup and on reload. Otherwise it behaves as a server with jwt.enable = false and has no debug create-jwt command. ID tokens issued by the native OIDC server are unaffected.
ldap✔️Authenticate users against LDAP. Enable and configure [global.ldap]; an LDAP server is needed.
lz4_compression✔️LZ4 compression for RocksDB. Select rocksdb.compression_algo = "lz4" or "lz4hc".
markdown✔️Render Markdown to HTML in the server’s administrative messages: admin command output, admin room notices and the welcome message, and room and user reports. A build without it sends their Markdown source as plain text.
mas✔️Matrix Authentication Service provisioning API. Required when authentication.mas_secret is set; a build without it refuses to start with a nonempty secret.
media_thumbnail✔️Generate media thumbnails. Video extraction also needs media.video_thumbnail.command and its external program.
oidc✔️Native OIDC server API. Required when well_known.client is set together with authentication.oidc.native_auth or any identity_provider; a build without it refuses to start then. Legacy SSO alone does not need this feature, but SSO with well_known.client set does.
perf_measurements×Export tracing spans and write flamegraph data. Enable telemetry.jaeger.enable with an OTLP collector, or tracing.flame.enable with a writable tracing.flame.output_path.
release_max_log_level✔️Omit debug and trace logging from release builds. Remove this feature to use those log levels in a release build; runtime log filters cannot restore messages omitted at compile time.
s3_storage✔️Store media on Amazon S3 and S3-compatible services through [global.storage_provider.<ID>.s3] providers. Supports presigned download redirects (media.allow_redirect). Required when such a section sets url or bucket; a build without it refuses to start then.
sentry_telemetry✔️Sentry error reporting and tracing integration. Enable telemetry.sentry.enable and configure telemetry.sentry.endpoint.
synapse_admin✔️Synapse admin API, client account suspend and lock endpoints, and the client whois alias. Most endpoints require an administrator token; shared-secret registration requires registration.shared_secret.
systemd✔️Systemd readiness, watchdog, socket activation, and configuration reload notifications. Requires Linux and systemd.
tokio_console×Tokio task instrumentation for tokio-console. Build with --cfg tokio_unstable, enable tracing.tokio_console and logging.global_default, and omit release_max_log_level for release builds.
tuwunel_mods×Hot reloadable development modules. Build with --cfg tuwunel_mods and provide loadable modules; see Hot Reloading.
url_preview✔️Fetch URL previews for clients. Configure media.url_preview.domain_contains_allowlist or media.url_preview.domain_explicit_allowlist for permitted domains.
zstd_compression✔️Zstd HTTP compression/decompression and RocksDB compression. HTTP uses http.compression.zstd = true and client negotiation; network.http.zstd controls outbound negotiation; RocksDB uses rocksdb.compression_algo.

Local filesystem providers, including the default media provider, and the query storage admin commands work independently of gcs_storage and s3_storage.

Journal logging works independently of the systemd feature. It requires logging.journald and the presence of both SYSTEMD_EXEC_PID and JOURNAL_STREAM in the environment.

Important

Some features reject enabling configuration when absent from the build; see the individual descriptions above.

Note

  • The oidc, mas, and synapse_admin features can each be left out independently.

Feature projection and dependency implications

The main crate defines every public feature and forwards it to the workspace crates that apply it. The crate column lists those crates, whether they use the feature in conditional code or to enable a dependency feature. The last column lists direct optional dependencies enabled along the forwarding path and feature changes to existing dependencies.

FeatureCrates involvedDependency implications
brotli_compressionapi, core, router, serviceCompression features on existing HTTP dependencies.
bzip2_compressiondatabaseRocksDB Bzip2 support.
consoleservicerustyline-async, termimad.
cpu_affinitycorecore_affinity.
direct_tlsrouteraxum-server-dual-protocol, rustls.
element_hacksserviceNo optional dependency activated by this feature.
emailservicelettre.
gcs_storageserviceobject_store’s gcp feature, which adds its cloud client and quick-xml.
gzip_compressionapi, core, router, serviceCompression features on existing HTTP dependencies.
io_uringdatabaseRocksDB io_uring support and its native library requirements.
jemalloccore, databasejevmalloc; native allocator build.
jemalloc_confcoreAllocator configuration; does not itself enable jemalloc.
jemalloc_profcoreProfiling on jevmalloc if the allocator is enabled.
jemalloc_statscoreStatistics on jevmalloc if the allocator is enabled.
jwt_loginadmin, api, api-client, corejsonwebtoken’s use_pem feature, which adds pem and simple_asn1. jsonwebtoken itself stays for the native OIDC server.
ldapapi, api-client, serviceldap3.
lz4_compressiondatabaseRocksDB LZ4 support.
markdownserviceRuma’s markdown feature, which adds pulldown-cmark.
masapi-mas, routerOptional workspace crate tuwunel-api-mas.
media_thumbnailserviceimage.
oidcapi-oidc, routerOptional workspace crate tuwunel-api-oidc; service-side issuer code remains compiled without this API feature.
perf_measurementsNoneopentelemetry, opentelemetry-otlp, opentelemetry_sdk, tracing-flame, tracing-opentelemetry.
release_max_log_leveladmin, api, api-admin, api-client, api-federation, api-mas, api-oidc, core, database, matrix, router, serviceLog-level filtering on existing log and tracing dependencies.
s3_storageserviceobject_store’s aws feature, which adds its cloud client, crc-fast, md-5, quick-xml and spin.
sentry_telemetryrouterreqwest, sentry, sentry-tower, sentry-tracing.
synapse_adminapi-admin, routerOptional workspace crate tuwunel-api-admin.
systemdrouter, servicesd-notify on Linux Unix targets.
tokio_consoleNoneconsole-subscriber, plus Tokio tracing support.
tuwunel_modscorelibloading.
url_previewserviceimage, webpage.
zstd_compressionapi, core, database, router, serviceHTTP and RocksDB Zstd support.

Note

  • jemalloc_conf, jemalloc_prof, and jemalloc_stats do not select the allocator themselves.

  • image is shared by thumbnails and URL previews, so removing only one feature can leave that dependency enabled.

  • Shared dependencies can already be enabled by another feature.

Crate defaults

Each workspace crate that defines default lists its own default features and enables the default of each workspace dependency that defines one. A crate built alone, such as with cargo build -p tuwunel_service, gets the same features it has in the full server.

The default of main also enables these crate defaults. A build from the workspace root and a build of -p tuwunel therefore resolve the same features and share compiled artifacts.

To build a crate alone with a dependency’s feature, name the feature through that dependency. For example, use cargo build -p tuwunel_service --features tuwunel-core/jemalloc_prof.

Rust cfg selectors

These configurations are primarily developer debugging, instruments and internal controls. The workspace registers them with check-cfg so rustc accepts their spelling. Build recipes can supply them separately through Rust compiler flags. They can be enabled by default in .cargo/config.toml.

cfg nameOursDefaultCrates involvedDescription
core_intrinsics××coreUses the compiler breakpoint intrinsic rather than the x86_64 breakpoint fallback.
disable✔️×core, database, serviceMarks dormant or unfinished code. Enabling it can introduce conflicting definitions.
panic_trap✔️×mainInternal modular-loader panic-hook path; not a supported standalone build switch.
tokio_unstable××core, main, adminEnables unstable Tokio metrics and runtime controls; also required by tokio_console.
tuwunel_always_prove_sendness✔️×serviceAsks the trait solver to prove OnceServices is Send instead of using its manual implementation; increases compilation work.
tuwunel_always_prove_syncness✔️×serviceAsks the trait solver to prove OnceServices is Sync instead of using its manual implementation; increases compilation work.
tuwunel_debug_logging✔️×corePreserves the requested severity of debug-gated logging macros. Does not override compile-time maximum log levels.
tuwunel_mods✔️×core, mainEnables development hot-reload paths together with the Cargo feature of the same name.
unabridged✔️×database, serviceAdds fine-grained tracing spans.

Note

  • The tokio_console Cargo feature needs tokio_unstable.

  • The tuwunel_mods cfg and Cargo feature must both be enabled for hot reloading. See Hot Reloading for the modular build workflow.