Advanced configuration

Centrifugo has some options for which default values make sense for most applications. In many case you don't need (and you really should not) change them. This chapter is about such options.


Default: 128

Sets maximum number of different channel subscriptions single client can have.

Before Centrifugo v1.6.0 default value was 100.


Default: 255

Sets maximum length of channel name.


Default: 0

Maximum number of connections from user (with known ID) to Centrifugo node. By default - unlimited.


Default: 60

Interval in seconds Centrifugo aggregates metrics before making metrics snapshot.


Default: 65536

Maximum allowed size of request from client in bytes.


Default: 10485760

Maximum client message queue size in bytes to close slow reader connections. By default - 10mb.


Default: 0

Interval in seconds how often to send SockJS h-frames to client. Starting from v1.6.0 we don't use hearbeat SockJS frames as we use client to server pings.


Default: false

Enable websocket compression, see special chapter in docs.


Default: 0

By default Centrifugo runs on all available CPU cores. If you want to limit amount of cores Centrifugo can utilize in one moment use this option.

Advanced endpoint configuration.

After you started Centrifugo you have several endpoints available. As soon as you have not provided any extra options you have 3 endpoints by default.

Default endpoints.

First is SockJS endpoint - it's needed to serve client connections that use SockJS library:


Next is raw Websocket endpoint to serve client connections that use pure Websocket protocol:


And finally you have API endpoint to publish messages to channels (and execute other available API commands):


By default all endpoints work on port 8000. You can change it using port option:

    "port": "9000"

In production setup you will have your domain name in endpoint addresses above instead of localhost. Also if your Centrifugo will be behind proxy or load balancer software you most probably won't have ports in your endpoint addresses. What will always be the same as shown above are URL paths: /connection, /connection/websocket, /api/.

Let's look at possibilities to tweak available endpoints.

Admin endpoints.

First is enabling admin endpoints:

    "admin": true,
    "admin_password": "password",
    "admin_secret": "secret"

This makes the following endpoint available:


This is an endpoint for admin websocket connections. In most scenarios it's used only by our builtin web interface. You can read about web interface in dedicated chapter. Here we will just show how to enable it:

    "web": true,
    "admin": true,
    "admin_password": "password",
    "admin_secret": "secret"

After adding web option you can visit:


And see web interface. You can log into it using admin_password value we set above.

Debug endpoints.

Next, when Centrifugo started in debug mode some extra debug endpoints become available. To start in debug mode add debug option to config:

    "debug": true

And endpoint:


will show you useful info about internal state of Centrifugo instance. This info is especially helpful when troubleshooting.

Custom admin and API ports

We strongly recommend to not expose admin (web), debug and API endpoints to internet. In case of admin endpoints this step provides extra protection to /socket endpoint, web interface and debug endpoints. Protecting API endpoint will allow you to use insecure_api mode to omit signing of each API request.

So it's a good practice to protect admin and API endpoints with firewall. For example you can do this in location section of Nginx configuration.

Though sometimes you don't have access to 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 admin and API endpoints work.

To run admin endpoints on custom port use admin_port option:

    "admin_port": "10000"

So admin socket will work on address:


And debug page will be available on new custom admin port too:


To run API server on it's own port use api_port option:

    "api_port": "10001"

Now you should send API requests to: