Let's look at how Centrifugo can be configured.
This chapter describes configuration principles and some important configuration options. There are more options not mentioned here but described throughout the doc in the context of each individual server feature.
Centrifugo can be configured in several ways: using command-line flags (highest priority), environment variables (second priority after flags), configuration file (lowest priority).
Centrifugo supports several command-line flags. See
centrifugo -h for available flags. Command-line flags limited to most frequently used. In general, we suggest to avoid using flags for configuring Centrifugo in a production environment – prefer using environment variables or configuration file.
Command-line options have the highest priority when set than other ways to configure Centrifugo.
OS environment variables
All Centrifugo options can be set over env in the format
CENTRIFUGO_<OPTION_NAME> (i.e. option name with
CENTRIFUGO_ prefix, all in uppercase).
Setting options over env is mostly straightforward except namespaces – see how to set namespaces via env. Environment variables have the second priority after flags.
Boolean options can be set using strings according to Go language ParseBool function. I.e. to set
true you can just use
"true" value for an environment variable (or simply
"1"). To set
Also, array options, like
allowed_origins can be set over environment variables as a single string where values separated by a space. For example:
export CENTRIFUGO_ALLOWED_ORIGINS="https://mysite1.example.com https://mysite2.example.com"
For a nested object configuration (which we have, for example, in Centrifugo PRO ClickHouse analytics) it's still possible to use environment variables to set options. In this case replace nesting with
_ when constructing environment variable name.
Empty environment variables are considered unset (!) and will fall back to the next configuration source.
Configuration file supports all options mentioned in Centrifugo documentation and can be in one of three supported formats: JSON, YAML, or TOML. Config file options have the lowest priority among configuration sources (i.e. option set over environment variable is preferred over the same option in config file).
A simple way to start with Centrifugo is to run:
This command generates
config.json configuration file in a current directory. This file already has the minimal number of options set. So it's then possible to start Centrifugo:
centrifugo -c config.json
Config file formats
Centrifugo supports three configuration file formats: JSON, YAML, or TOML.
JSON config format
Here is an example of Centrifugo JSON configuration file:
api_key used for Centrifugo API endpoint authorization, see more in chapter about server HTTP API. Keep both values secret and never reveal them to clients.
allowed_origins option described below.
TOML config format
Centrifugo also supports TOML format for configuration file:
allowed_origins: [ "http://localhost:3000" ]
token_hmac_secret_key = "<YOUR-SECRET-STRING-HERE>"
api_key = "<YOUR-API-KEY-HERE>"
log_level = "debug"
In the example above we also defined logging level to be
debug which is useful to have while developing an application. In the production environment debug logging can be too chatty.
YAML config format
YAML format is also supported:
With YAML remember to use spaces, not tabs when writing a configuration file.
Let's describe some important options you can configure when running Centrifugo.
This option allows setting an array of allowed origin patterns (array of strings) for WebSocket and SockJS endpoints to prevent CSRF or WebSocket hijacking attacks. Also, it's used for HTTP-based unidirectional transports to enable CORS for configured origins.
As soon as
allowed_origins is defined every connection request with
Origin set will be checked against each pattern in an array.
Connection requests without
Origin header set are passing through without any checks (i.e. always allowed).
For example, a client connects to Centrifugo from a web browser application on
http://localhost:3000. In this case,
allowed_origins should be configured in this way:
When connecting from
Origin pattern can contain wildcard symbol
* to match subdomains:
– in this case requests with
Origin header like
https://bar.example.com will pass the check.
It's also possible to allow all origins in the following way (but this is discouraged and insecure when using connect proxy feature):
Bind your Centrifugo to a specific interface address (string, by default
"" - listen on all available interfaces).
Port to bind Centrifugo to (string, by default
Engine to use -
tarantool. It's a string option, by default
memory. Read more about engines in special chapter.
These options allow tweaking server behavior, in most cases default values are good to start with.
Sets the maximum number of different channel subscriptions a single client can have.
When designing an application avoid subscribing to an unlimited number of channels per one client. Keep number of subscriptions for each client reasonably small – this will help keeping handshake process lightweight and fast.
Sets the maximum length of the channel name.
The maximum number of connections from a user (with known user ID) to Centrifugo node. By default, unlimited.
The important thing to emphasize is that
client_user_connection_limit works only per one Centrifugo node and exists mostly to protect Centrifugo from many connections from a single user – but not for business logic limitations. This means that if you set this to 1 and scale nodes – say run 10 Centrifugo nodes – then a user will be able to create 10 connections (one to each node).
When set to a value > 0
client_connection_limit limits the max number of connections single Centrifugo node can handle. It acts on HTTP middleware level and stops processing request if the condition met. It logs a warning into logs in this case and increments
centrifugo_node_client_connection_limit Prometheus counter. Client SDKs will attempt reconnecting.
Some motivation behind this option may be found in this issue.
Note, that at this point
client_connection_limit does not affect connections coming over GRPC unidirectional transport.
client_connection_rate_limit sets the maximum number of HTTP requests to establish a new real-time connection a single Centrifugo node will accept per second (on real-time transport endpoints). All requests outside the limit will get 503 Service Unavailable code in response. Our SDKs handle this with backoff reconnection.
By default, no limit is used.
Note, that at this point
client_connection_rate_limit does not affect connections coming over GRPC unidirectional transport.
Maximum client message queue size in bytes to close slow reader connections. By default - 1mb.
client_concurrency when set tells Centrifugo that commands from a client must be processed concurrently.
By default, concurrency disabled – Centrifugo processes commands received from a client one by one. This means that if a client issues two RPC requests to a server then Centrifugo will process the first one, then the second one. If the first RPC call is slow then the client will wait for the second RPC response much longer than it could (even if the second RPC is very fast). If you set
client_concurrency to some value greater than 1 then commands will be processed concurrently (in parallel) in separate goroutines (with maximum concurrency level capped by
client_concurrency value). Thus, this option can effectively reduce the latency of individual requests. Since separate goroutines are involved in processing this mode adds some performance and memory overhead – though it should be pretty negligible in most cases. This option applies to all commands from a client (including subscribe, publish, presence, etc).
Duration, default: 10s
This option allows tuning the maximum time Centrifugo will wait for the connect frame (which contains authentication information) from the client after establishing connection. Default value should be reasonable for most use cases.
Available since v5.1.1
Usually to authenticate client connections with Centrifugo you need to use JWT authentication or connect proxy. Sometimes though it may be convenient to pass user ID information in incoming HTTP request headers. This is usually the case when application backend infrastructure has some authentication proxy (like Envoy, etc). This proxy may set authenticated user ID to some header and proxy requests further to Centrifugo.
client_user_id_http_header is set to some non-empty header name Centrifugo will try to extract the authenticated user ID for client connections from that header. This mechanism works for all real-time transports based on HTTP (this also includes WebSocket since it starts with HTTP Upgrade request). Example:
When using this way for user authentication – you can not set connection expiration and additional connection info which is possible to do using other authentication ways mentioned above.
When using authentication over proxy ensure your proxy strips the header you are using for auth if it comes from the client or forbids such requests to avoid malicious usage. Only your authentication proxy must set the header with user ID.
Enable a mode when all clients can connect to Centrifugo without JWT. In this case, all connections without a token will be treated as anonymous (i.e. with empty user ID). Access to channel operations should be explicitly enabled for anonymous connections.
When the option is set Centrifugo won't accept connections from anonymous users even if they provided a valid JWT. I.e. if token is valid, but
sub claim is empty – then Centrifugo closes connection with advice to not reconnect again.
By default, Centrifugo runs on all available CPU cores (also Centrifugo can look at cgroup limits when rnning in Docker/Kubernetes). To limit the number of cores Centrifugo can utilize in one moment use this option.
After Centrifugo started there are several endpoints available.
Bidirectional WebSocket default endpoint:
Bidirectional emulation with HTTP-streaming (disabled by default):
Bidirectional emulation with SSE (EventSource) (disabled by default):
Bidirectional SockJS default endpoint (disabled by default):
Unidirectional EventSource endpoint (disabled by default):
Unidirectional HTTP streaming endpoint (disabled by default):
Unidirectional WebSocket endpoint (disabled by default):
Unidirectional SSE (EventSource) endpoint (disabled by default):
Server HTTP API endpoint:
By default, all endpoints work on port
8000. This can be changed with
In production setup, you may have a proper domain name in endpoint addresses above instead of
localhost. While domain name and port parts can differ depending on setup – URL paths stay the same:
Admin web UI endpoint works on root path by default, i.e.
For more details about admin web UI, refer to the Admin web UI documentation.
Next, when Centrifugo started in debug mode some extra debug endpoints become available. To start in debug mode add
debug option to config:
– will show useful information about the internal state of Centrifugo instance. This info is especially helpful when troubleshooting. See wiki page for more info.
Health check endpoint
health boolean option (by default
false) to enable the health check endpoint which will be available on path
/health. Also available over command-line flag:
centrifugo -c config.json --health
Swagger UI for server API
swagger boolean option (by default
false) to enable Swagger UI for server HTTP API. UI will be available on path
/swagger. Also available over command-line flag:
centrifugo -c config.json --swagger
Custom internal ports
We strongly recommend not expose API, admin, debug, health, and Prometheus endpoints to the Internet. The following Centrifugo endpoints are considered internal:
- API endpoint (
/api) - for HTTP API requests
- Admin web interface endpoints (
/admin/api) - used by web interface
- Prometheus endpoint (
/metrics) - used for exposing server metrics in Prometheus format
- Health check endpoint (
/health) - used to do health checks
- Debug endpoints (
/debug/pprof) - used to inspect internal server state
- Swagger UI endpoint (
/swagger) - used for showing embedded Swagger UI for server HTTP API
It's a good practice to protect all these endpoints with a firewall. For example, it's possible to configure in
location section of the Nginx configuration.
Though sometimes you don't have access to a per-location configuration in your proxy/load balancer software. For example when using Amazon ELB. In this case, you can change ports on which your internal endpoints work.
To run internal endpoints on custom port use
So admin web interface will work on address:
Also, debug page will be available on a new custom port too:
The same for API and Prometheus endpoints.
Disable default endpoints
To disable websocket endpoint set
websocket_disable boolean option to
To disable API endpoint set
api_disable boolean option to
Customize handler endpoints
It's possible to customize server HTTP handler endpoints. To do this Centrifugo supports several options:
"") - to control Admin panel URL prefix
"/connection/websocket") - to control WebSocket URL prefix
"/connection/http_stream") - to control HTTP-streaming URL prefix
"/connection/sse") - to control SSE/EventSource URL prefix
"/emulation") - to control emulation endpoint prefix
"/connection/sockjs") - to control SockJS URL prefix
"/connection/uni_sse") - to control unidirectional Eventsource URL prefix
"/connection/uni_http_stream") - to control unidirectional HTTP streaming URL prefix
"/connection/uni_websocket") - to control unidirectional WebSocket URL prefix
"/api") - to control HTTP API URL prefix
"/metrics") - to control Prometheus URL prefix
"/health") - to control health check URL prefix
It's possible to send HUP signal to Centrifugo to reload a configuration:
kill -HUP <PID>
Though at moment this will only reload token secrets and channel options (top-level and namespaces).
Centrifugo tries to gracefully shut down client connections when SIGINT or SIGTERM signals are received. By default, the maximum graceful shutdown period is 30 seconds but can be changed using
shutdown_timeout (integer, in seconds) configuration option.
Insecure client connection
The boolean option
false) allows connecting to Centrifugo without JWT token. In this mode, there is no user authentication involved. It also disables permission checks on client API level - for presence and history calls. This mode can be useful for demo projects based on Centrifugo, integration tests, local projects, or real-time application prototyping. Don't use it in production until you 100% know what you are doing.
Disable client token signature check
Available since Centrifugo v5.0.4
The boolean option
false), if enabled – tells Centrifugo to skip JWT signature verification - for both connection and subscription tokens. This is absolutely insecure and must only be used for development and testing purposes. Token claims are parsed as usual - so token should still follow JWT format.
Insecure API mode
This mode can be enabled using the boolean option
false). When on there is no need to provide API key in HTTP requests. When using this mode everyone that has access to
/api endpoint can send any command to server. Enabling this option can be reasonable if
/api endpoint is protected by firewall rules.
The option is also useful in development to simplify sending API commands to Centrifugo using CURL for example without specifying
Authorization header in requests.
Insecure admin mode
This mode can be enabled using the boolean option
false). When on there is no authentication in the admin web interface. Again - this is not secure but can be justified if you protected the admin interface by firewall rules or you want to use basic authentication for the Centrifugo admin interface (configured on proxy level).