Powered by nginx

Nchan is a scalable, flexible pub/sub server for the modern web, built as a module for the Nginx web server. It can be configured as a standalone server, or as a shim between your application and hundreds, thousands, or millions of live subscribers. It can buffer messages in memory, on-disk, or via Redis. All connections are handled asynchronously and distributed among any number of worker processes. It can also scale to many Nginx servers with Redis.

Messages are published to channels with HTTP POST requests or Websocket, and subscribed also through Websocket, long-polling, EventSource (SSE), old-fashioned interval polling, and more.

In a web browser, you can use Websocket or EventSource natively, or the NchanSubscriber.js wrapper library. It supports Long-Polling, EventSource, and resumable Websockets, and has a few other added convenience options. It's also available on NPM.

Features

Status and History

The latest Nchan release is 1.3.7 (September 19, 2024) (changelog).

The first iteration of Nchan was written in 2009-2010 as the Nginx HTTP Push Module, and was vastly refactored into its present state in 2014-2016.

Upgrade from Nginx HTTP Push Module

Although Nchan is backwards-compatible with all Push Module configuration directives, some of the more unusual and rarely used settings have been disabled and will be ignored (with a warning). See the upgrade page for a detailed list of changes and improvements, as well as a full list of incompatibilities.

Does it scale?

benchmarking internal subscriber response times

Yes it does. Like Nginx, Nchan can easily handle as much traffic as you can throw at it. I've tried to benchmark it, but my benchmarking tools are much slower than Nchan. The data I've gathered is on how long Nchan itself takes to respond to every subscriber after publishing a message -- this excludes TCP handshake times and internal HTTP request parsing. Basically, it measures how Nchan scales assuming all other components are already tuned for scalability. The graphed data are averages of 5 runs with 50-byte messages.

With a well-tuned OS and network stack on commodity server hardware, expect to handle upwards of 300K concurrent subscribers per second at minimal CPU load. Nchan can also be scaled out to multiple Nginx instances using the Redis storage engine, and that too can be scaled up beyond a single-point-of-failure by using Redis Cluster.

Install

Download Packages

Build From Source

Grab the latest copy of Nginx from nginx.org. Grab the latest Nchan source from github. Follow the instructions for building Nginx, except during the configure stage, add

./configure --add-module=path/to/nchan ...

If you're using Nginx > 1.9.11, you can build Nchan as a dynamic module with --add-dynamic-module=path/to/nchan

Run make, then make install.

Getting Started

Once you've built and installed Nchan, it's very easy to start using. Add two locations to your nginx config:

#...
http {  
  server {
    #...

    location = /sub {
      nchan_subscriber;
      nchan_channel_id $arg_id;
    }

    location = /pub {
      nchan_publisher;
      nchan_channel_id $arg_id;
    }
  }
}

You can now publish messages to channels by POSTing data to /pub?id=channel_id , and subscribe by pointing Websocket, EventSource, or NchanSubscriber.js to sub/?id=channel_id. It's that simple.

But Nchan is very flexible and highly configurable. So, of course, it can get a lot more complicated...

Conceptual Overview

The basic unit of most pub/sub solutions is the messaging channel. Nchan is no different. Publishers send messages to channels with a certain channel id, and subscribers subscribed to those channels receive them. Some number of messages may be buffered for a time in a channel's message buffer before they are deleted. Pretty simple, right?

Well... the trouble is that nginx configuration does not deal with channels, publishers, and subscribers. Rather, it has several sections for incoming requests to match against server and location sections. Nchan configuration directives map servers and locations onto channel publishing and subscribing endpoints:

#very basic nchan config
worker_processes 5;

http {  
  server {
    listen       80;

    location = /sub {
      nchan_subscriber;
      nchan_channel_id foobar;
    }

    location = /pub {
      nchan_publisher;
      nchan_channel_id foobar;
    }
  }
}

The above maps requests to the URI /sub onto the channel foobar's subscriber endpoint , and similarly /pub onto channel foobar's publisher endpoint.

Publisher Endpoints

Publisher endpoints are Nginx config locations with the nchan_publisher directive.

Messages can be published to a channel by sending HTTP POST requests with the message contents to the publisher endpoint locations. You can also publish messages through a Websocket connection to the same location.

  location /pub {
    #example publisher location
    nchan_publisher;
    nchan_channel_id foo;
    nchan_channel_group test;
    nchan_message_buffer_length 50;
    nchan_message_timeout 5m;
  }
related configuration: nchan_deflate_message_for_websocket, nchan_publisher, nchan_publisher_upstream_request, nchan_pubsub, nchan_access_control_allow_credentials, nchan_access_control_allow_origin, nchan_authorize_request, nchan_channel_group, nchan_max_channel_id_length, nchan_message_buffer_length, nchan_message_timeout, nchan_redis_nostore_fastpublish, nchan_redis_pass, nchan_store_messages, nchan_use_redis, nchan_channel_event_string, nchan_channel_events_channel_id

Publishing Messages

Requests and websocket messages are responded to with information about the channel at time of message publication. Here's an example from publishing with curl:

>  curl --request POST --data "test message" http://127.0.0.1:80/pub

 queued messages: 5
 last requested: 18 sec. ago
 active subscribers: 0
 last message id: 1450755280:0

The response can be in plaintext (as above), JSON, or XML, based on the request's Accept header:

> curl --request POST --data "test message" -H "Accept: text/json" http://127.0.0.2:80/pub

 {"messages": 5, "requested": 18, "subscribers": 0, "last_message_id": "1450755280:0" }

Websocket publishers also receive the same responses when publishing, with the encoding determined by the Accept header present during the handshake.

The response code for an HTTP request is 202 Accepted if no subscribers are present at time of publication, or 201 Created if at least 1 subscriber was present.

Metadata can be added to a message when using an HTTP POST request for publishing. A Content-Type header will be associated as the message's content type (and output to Long-Poll, Interval-Poll, and multipart/mixed subscribers). A X-EventSource-Event header can also be used to associate an EventSource event: line value with a message.

Other Publisher Endpoint Actions

HTTP GET requests return channel information without publishing a message. The response code is 200 if the channel exists, and 404 otherwise: 

> curl --request POST --data "test message" http://127.0.0.2:80/pub
  ...

> curl -v --request GET -H "Accept: text/json" http://127.0.0.2:80/pub

 {"messages": 1, "requested": 7, "subscribers": 0, "last_message_id": "1450755421:0" }

HTTP DELETE requests delete a channel and end all subscriber connections. Like the GET requests, this returns a 200 status response with channel info if the channel existed, and a 404 otherwise.

How Channel Settings Work

A channel's configuration is set to the that of its last-used publishing location. So, if you want a channel to behave consistently, and want to publish to it from multiple locations, make sure those locations have the same configuration.

You can also can use differently-configured publisher locations to dynamically update a channel's message buffer settings. This can be used to erase messages or to scale an existing channel's message buffer as desired.

Subscriber Endpoints

Subscriber endpoints are Nginx config locations with the nchan_subscriber directive.

Nchan supports several different kinds of subscribers for receiving messages: Websocket, EventSource (Server Sent Events), Long-Poll, Interval-Poll. HTTP chunked transfer, and HTTP multipart/mixed.

  location /sub {
    #example subscriber location
    nchan_subscriber;
    nchan_channel_id foo;
    nchan_channel_group test;
    nchan_subscriber_first_message oldest;
  }
related configuration: nchan_pubsub, nchan_subscribe_request, nchan_subscriber, nchan_subscriber_compound_etag_message_id, nchan_subscriber_first_message, nchan_subscriber_info, nchan_subscriber_info_string, nchan_subscriber_last_message_id, nchan_subscriber_message_id_custom_etag_header, nchan_subscriber_timeout, nchan_unsubscribe_request, nchan_access_control_allow_credentials, nchan_access_control_allow_origin, nchan_authorize_request, nchan_channel_group, nchan_max_channel_id_length, nchan_max_channel_subscribers, nchan_subscribe_existing_channels_only, nchan_redis_pass, nchan_use_redis, nchan_channel_event_string, nchan_channel_events_channel_id

PubSub Endpoint

PubSub endpoints are Nginx config locations with the nchan_pubsub directive.

A combination of publisher and subscriber endpoints, this location treats all HTTP GET requests as subscribers, and all HTTP POST as publishers. Channels cannot be deleted through a pubsub endpoing with an HTTP DELETE request.

One simple use case is an echo server:

  location = /pubsub {
    nchan_pubsub;
    nchan_channel_id foo;
    nchan_channel_group test;
  }

A more interesting setup may set different publisher and subscriber channel ids:

  location = /pubsub {
    nchan_pubsub;
    nchan_publisher_channel_id foo;
    nchan_subscriber_channel_id bar;
    nchan_channel_group test;
  }

Here, subscribers will listen for messages on channel foo, and publishers will publish messages to channel bar. This can be useful when setting up websocket proxying between web clients and your application.

related configuration: nchan_publisher_channel_id, nchan_pubsub, nchan_subscriber_channel_id

The Channel ID

So far the examples have used static channel ids, which is not very useful. In practice, the channel id can be set to any nginx variable, such as a querystring argument, a header value, or a part of the location url:

  location = /sub_by_ip {
    #channel id is the subscriber's IP address
    nchan_subscriber;
    nchan_channel_id $remote_addr;
  }

  location /sub_by_querystring {
    #channel id is the query string parameter chanid
    # GET /sub/sub_by_querystring?foo=bar&chanid=baz will have the channel id set to 'baz'
    nchan_subscriber;
    nchan_channel_id $arg_chanid;
  }

  location ~ /sub/(\w+)$ {
    #channel id is the word after /sub/
    # GET /sub/foobar_baz will have the channel id set to 'foobar_baz'
    # I hope you know your regular expressions...
    nchan_subscriber;
    nchan_channel_id $1; #first capture of the location match
  }

I recommend using the last option, a channel id derived from the request URL via a regular expression. It makes things nice and RESTful.

related configuration: nchan_channel_id, nchan_channel_id_split_delimiter, nchan_publisher_channel_id, nchan_subscriber_channel_id, nchan_max_channel_id_length

Channel Multiplexing

With channel multiplexing, subscribers can subscribe to up to 255 channels per connection. Messages published to all the specified channels will be delivered in-order to the subscriber. There are two ways to enable multiplexing:

Up to 7 channel ids can be specified for the nchan_channel_id or nchan_channel_subscriber_id config directive:

  location ~ /multisub/(\w+)/(\w+)$ {
    nchan_subscriber;
    nchan_channel_id "$1" "$2" "common_channel";
    #GET /multisub/foo/bar will be subscribed to:
    # channels 'foo', 'bar', and 'common_channel',
    #and will receive messages from all of the above.
  }

For more than 7 channels, nchan_channel_id_split_delimiter can be used to split the nchan_channel_id or nchan_channel_subscriber_id into up to 255 individual channel ids:

  location ~ /multisub-split/(.*)$ {
    nchan_subscriber;
    nchan_channel_id "$1";
    nchan_channel_id_split_delimiter ",";
    #GET /multisub-split/foo,bar,baz,a will be subscribed to:
    # channels 'foo', 'bar', 'baz', and 'a'
    #and will receive messages from all of the above.
  }

It is also possible to publish to multiple channels with a single request as well as delete multiple channels with a single request, with similar configuration:

  location ~ /multipub/(\w+)/(\w+)$ {
    nchan_publisher;
    nchan_channel_id "$1" "$2" "another_channel";
    #POST /multipub/foo/bar will publish to:
    # channels 'foo', 'bar', 'another_channel'
    #DELETE /multipub/foo/bar will delete:
    # channels 'foo', 'bar', 'another_channel'
  }

When a channel is deleted, all of its messages are deleted, and all of its subscribers' connection are closed -- including ones subscribing through a multiplexed location. For example, suppose a subscriber is subscribed to channels "foo" and "bar" via a single multiplexed connection. If "foo" is deleted, the connection is closed, and the subscriber therefore loses the "bar" subscription as well.

See the Channel Security section about using good IDs and keeping private channels secure.

related configuration: nchan_channel_id_split_delimiter

Channel Groups

Channels can be associated with groups to avoid channel ID conflicts:

  location /test_pubsub {
    nchan_pubsub;
    nchan_channel_group "test";
    nchan_channel_id "foo";
  }

  location /pubsub {
    nchan_pubsub;
    nchan_channel_group "production";
    nchan_channel_id "foo";
    #same channel id, different channel group. Thus, different channel.
  }

  location /flexgroup_pubsub {
    nchan_pubsub;
    nchan_channel_group $arg_group;
    nchan_channel_id "foo";
    #group can be set with request variables too
  }

Limits and Accounting

Groups can be used to track aggregate channel usage, as well as set limits on the number of channels, subscribers, stored messages, memory use, etc:

  #enable group accounting
  nchan_channel_group_accounting on;

  location ~ /pubsub/(\w+)$ {
    nchan_pubsub;
    nchan_channel_group "limited";
    nchan_channel_id $1;
  }

  location ~ /prelimited_pubsub/(\w+)$ {
    nchan_pubsub;
    nchan_channel_group "limited";
    nchan_channel_id $1;
    nchan_group_max_subscribers 100;
    nchan_group_max_messages_memory 50M;
  }

  location /group {
    nchan_channel_group limited;
    nchan_group_location;
    nchan_group_max_channels $arg_max_channels;
    nchan_group_max_messages $arg_max_messages;
    nchan_group_max_messages_memory $arg_max_messages_mem;
    nchan_group_max_messages_disk $arg_max_messages_disk;
    nchan_group_max_subscribers $arg_max_subs;
  }

Here, /group is an nchan_group_location, which is used for accessing and modifying group data. To get group data, send a GET request to a nchan_group_location:

>  curl http://localhost/group

channels: 10
subscribers: 0
messages: 219
shared memory used by messages: 42362 bytes
disk space used by messages: 0 bytes
limits:
  max channels: 0
  max subscribers: 0
  max messages: 0
  max messages shared memory: 0
  max messages disk space: 0

By default, the data is returned in human-readable plaintext, but can also be formatted as JSON, XML, or YAML:

>  curl -H "Accept: text/json" http://localhost/group

{
  "channels": 21,
  "subscribers": 40,
  "messages": 53,
  "messages_memory": 19941,
  "messages_disk": 0,
  "limits": {
    "channels": 0,
    "subscribers": 0,
    "messages": 0,
    "messages_memory": 0,
    "messages_disk": 0
  }
}

The data in the response are for the single Nchan instance only, regardless of whether Redis is used. A limit of 0 means 'unlimited'.

Limits can be set per-location, as with the above /prelimited_pubsub/... location, or with a POST request to the nchan_group_location:

>  curl -X POST "http://localhost/group?max_channels=15&max_subs=1000&max_messages_disk=0.5G"

channels: 0
subscribers: 0
messages: 0
shared memory used by messages: 0 bytes
disk space used by messages: 0 bytes
limits:
  max channels: 15
  max subscribers: 1000
  max messages: 0
  max messages shared memory: 0
  max messages disk space: 536870912

Limits are only applied locally, regardless of whether Redis is enabled. If a publisher or subscriber request exceeds a group limit, Nchan will respond to it with a 403 Forbidden response.

related configuration: nchan_channel_group, nchan_channel_group_accounting, nchan_group_location, nchan_group_max_channels, nchan_group_max_messages, nchan_group_max_messages_disk, nchan_group_max_messages_memory, nchan_group_max_subscribers

Hooks and Callbacks

related configuration: nchan_publisher_upstream_request, nchan_subscribe_request, nchan_unsubscribe_request, nchan_authorize_request

Request Authorization

This feature, configured with nchan_authorize_request, behaves just like the Nginx http_auth_request module.

Consider the configuration:

  upstream my_app {
    server 127.0.0.1:8080;
  }
  location = /auth {
    proxy_pass http://my_app/pubsub_authorize;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Subscriber-Type $nchan_subscriber_type;
    proxy_set_header X-Publisher-Type $nchan_publisher_type;
    proxy_set_header X-Prev-Message-Id $nchan_prev_message_id;
    proxy_set_header X-Channel-Id $nchan_channel_id;
    proxy_set_header X-Original-URI $request_uri;
    proxy_set_header X-Forwarded-For $remote_addr;
  }

  location ~ /pubsub/auth/(\w+)$ {
    nchan_channel_id $1;
    nchan_authorize_request /auth;
    nchan_pubsub;
    nchan_channel_group test;
  }

Here, any request to the location /pubsub/auth/<...> will need to be authorized by your application (my_app). Nginx will generate a GET /pubsub_authorize request to the application, with additional headers set by the proxy_set_header directives. Note that Nchan-specific variables are available for this authorization request. Once your application receives this request, it should decide whether or not to authorize the subscriber. This can be done based on a forwarded session cookie, IP address, or any set of parameters of your choosing. If authorized, it should respond with an empty 200 OK response.
All non-2xx response codes (such as 403 Forbidden) are interpreted as authorization failures. In this case, the failing response is proxied to the client.

Note that Websocket and EventSource clients will only try to authorize during the initial handshake request, whereas Long-Poll and Interval-Poll subscribers will need to be authorized each time they request the next message, which may flood your application with too many authorization requests.

related configuration: nchan_authorize_request

Subscriber Presence

Subscribers can notify an application when they have subscribed and unsubscribed to a channel using the nchan_subscribe_request and nchan_unsubscribe_request settings. These should point to Nginx locations configured to forward requests to an upstream proxy (your application):

  location ~ /sub/(\w+)$ {
    nchan_channel_id $1;
    nchan_subscribe_request /upstream/sub;
    nchan_unsubscribe_request /upstream/unsub;
    nchan_subscriber;
    nchan_channel_group test;
  }

  location = /upstream/unsub {
    proxy_pass http://127.0.0.1:9292/unsub;
    proxy_ignore_client_abort on;  #!!!important!!!!
    proxy_set_header X-Subscriber-Type $nchan_subscriber_type;
    proxy_set_header X-Channel-Id $nchan_channel_id;
    proxy_set_header X-Original-URI $request_uri;
  } 
  location = /upstream/sub {
    proxy_pass http://127.0.0.1:9292/sub;
    proxy_set_header X-Subscriber-Type $nchan_subscriber_type;
    proxy_set_header X-Message-Id $nchan_message_id;
    proxy_set_header X-Channel-Id $nchan_channel_id;
    proxy_set_header X-Original-URI $request_uri;
  }

In order for nchan_unsubscribe_request to work correctly, the location it points to must have proxy_ignore_client_abort on;. Otherwise, suddenly aborted subscribers may not trigger an unsubscribe request.

Note that the subscribe/unsubscribe hooks are disabled for long-poll and interval-poll clients, because they would trigger these hooks each time they receive a message.

related configuration: nchan_subscribe_request, nchan_unsubscribe_request

Message Forwarding

Messages can be forwarded to an upstream application before being published using the nchan_publisher_upstream_request setting:

  location ~ /pub/(\w+)$ {
    #publisher endpoint
    nchan_channel_id $1;
    nchan_pubsub;
    nchan_publisher_upstream_request /upstream_pub;
  }

  location = /upstream_pub {
    proxy_pass http://127.0.0.1:9292/pub;
    proxy_set_header X-Publisher-Type $nchan_publisher_type;
    proxy_set_header X-Prev-Message-Id $nchan_prev_message_id;
    proxy_set_header X-Channel-Id $nchan_channel_id;
    proxy_set_header X-Original-URI $request_uri;
  }

With this configuration, incoming messages are first POSTed to http://127.0.0.1:9292/pub. The upstream response code determines how publishing will proceed:

There are two main use cases for nchan_publisher_upstream_request: forwarding incoming data from Websocket publishers to an application, and mutating incoming messages.

related configuration: nchan_publisher_upstream_request

Storage

Nchan can stores messages in memory, on disk, or via Redis. Memory storage is much faster, whereas Redis has additional overhead as is considerably slower for publishing messages, but offers near unlimited scalability for broadcast use cases with far more subscribers than publishers.

Memory Storage

This default storage method uses a segment of shared memory to store messages and channel data. Large messages as determined by Nginx's caching layer are stored on-disk. The size of the memory segment is configured with nchan_shared_memory_size. Data stored here is not persistent, and is lost if Nginx is restarted or reloaded.

related configuration: nchan_message_temp_path, nchan_shared_memory_size

Redis

Redis can be used to add data persistence and horizontal scalability, failover and high availability to your Nchan setup.

related configuration: nchan_redis_accurate_subscriber_count, nchan_redis_cluster_check_interval_backoff, nchan_redis_cluster_check_interval_jitter, nchan_redis_cluster_check_interval_max, nchan_redis_cluster_check_interval_min, nchan_redis_cluster_connect_timeout, nchan_redis_cluster_max_failing_time, nchan_redis_cluster_recovery_delay, nchan_redis_cluster_recovery_delay_backoff, nchan_redis_cluster_recovery_delay_jitter, nchan_redis_cluster_recovery_delay_max, nchan_redis_command_timeout, nchan_redis_connect_timeout, nchan_redis_discovered_ip_range_blacklist, nchan_redis_idle_channel_cache_timeout, nchan_redis_namespace, nchan_redis_nostore_fastpublish, nchan_redis_optimize_target, nchan_redis_pass, nchan_redis_password, nchan_redis_ping_interval, nchan_redis_reconnect_delay, nchan_redis_reconnect_delay_backoff, nchan_redis_reconnect_delay_jitter, nchan_redis_reconnect_delay_max, nchan_redis_retry_commands, nchan_redis_retry_commands_max_wait, nchan_redis_server, nchan_redis_ssl, nchan_redis_ssl_ciphers, nchan_redis_ssl_client_certificate, nchan_redis_ssl_client_certificate_key, nchan_redis_ssl_server_name, nchan_redis_ssl_trusted_certificate, nchan_redis_ssl_trusted_certificate_path, nchan_redis_ssl_verify_certificate, nchan_redis_storage_mode, nchan_redis_subscribe_weights, nchan_redis_upstream_stats, nchan_redis_upstream_stats_disconnected_timeout, nchan_redis_upstream_stats_enabled, nchan_redis_url, nchan_redis_username, nchan_use_redis

Connecting to a Redis Server

To connect to a single Redis master server, use an upstream with nchan_redis_server and nchan_redis_pass settings:

http {
  upstream my_redis_server {
    nchan_redis_server 127.0.0.1;
  }
  server {
    listen 80;

    location ~ /redis_sub/(\w+)$ {
      nchan_subscriber;
      nchan_channel_id $1;
      nchan_redis_pass my_redis_server;
    }
    location ~ /redis_pub/(\w+)$ {
      nchan_redis_pass my_redis_server;
      nchan_publisher;
      nchan_channel_id $1;
    }
  }
}

All servers with the above configuration connecting to the same redis server share channel and message data.

Channels that don't use Redis can be configured side-by-side with Redis-backed channels, provided the endpoints never overlap. (This can be ensured, as above, by setting separate nchan_channel_groups.). Different locations can also connect to different Redis servers.

Nchan can work with a single Redis master. It can also auto-discover and use Redis slaves to balance PUBSUB traffic.

related configuration: nchan_redis_server, nchan_redis_pass

Redis Cluster

Nchan also supports using Redis Cluster, which adds scalability via sharding channels among cluster nodes. Redis cluster also provides automatic failover, high availability, and eliminates the single point of failure of one shared Redis server. It is configured and used like so:

http {
  upstream redis_cluster {
    nchan_redis_server redis://127.0.0.1:7000;
    nchan_redis_server redis://127.0.0.1:7001;
    nchan_redis_server redis://127.0.0.1:7002;
    # you don't need to specify all the nodes, they will be autodiscovered
    # however, it's recommended that you do specify at least a few master nodes.
  }
  server {
    listen 80;

    location ~ /sub/(\w+)$ {
      nchan_subscriber;
      nchan_channel_id $1;
      nchan_redis_pass redis_cluster;
    }
    location ~ /pub/(\w+)$ {
      nchan_publisher;
      nchan_channel_id $1;
      nchan_redis_pass redis_cluster;
    }
  }
}
related configuration: nchan_redis_server, nchan_redis_pass
High Availability

Redis Cluster connections are designed to be resilient and try to recover from errors. Interrupted connections will have their commands queued until reconnection, and Nchan will publish any messages it successfully received while disconnected. Nchan is also adaptive to cluster modifications. It will add new nodes and remove them as needed.

All Nchan servers sharing a Redis server or cluster should have their times synchronized (via ntpd or your favorite ntp daemon). Failure to do so may result in missed or duplicate messages.

Failover Recovery

Starting with version 1.3.0, Nchan will attempt to recover from cluster node failures, keyslot errors, and cluster epoch changes without disconnecting from the entire cluster. It will attempt to do this until nchan_redis_cluster_max_failing_time is exceeded. Additionally, recovery attempt delays have configurable jitter, exponential backoff, and maximum values.

Using Redis securely

Redis servers can be connected to via TLS by using the nchan_redis_ssl config setting in an upstream block, or by using the rediss:// schema for the server URLs.

A password and optional username for the AUTH command can be set by the nchan_redis_username and nchan_redis_password config settings in an upstream block, or by using the redis://<username>:<password>@hostname server URL schema.

Note that autodiscovered Redis nodes inherit their parent's SSL, username, and password settings.

Tweaks and Optimizations

As of version 1.2.0, Nchan uses Redis slaves to load-balance PUBSUB traffic. By default, there is an equal chance that a channel's PUBSUB subscription will go to any master or slave. The nchan_redis_subscribe_weights setting is available to fine-tune this load-balancing.

Also from 1.2.0 onward, nchan_redis_optimize_target can be used to prefer optimizing Redis slaves for CPU or bandwidth. For heavy publishing loads, the tradeoff is very roughly 35% replication bandwidth per slave to 30% CPU load on slaves.

Performance Statistics

Redis command statistics were added in version 1.3.5. These provide total number of times different Redis commands were run on, and the total amount of time they took. The stats are for a given Nchan server, not all servers connected to a Redis upstream. They are grouped by each upstream, and totaled per node.

http {
  upstream my_redis_cluster {
    nchan_redis_server 127.0.0.1;
  }

  server {
    #[...]

    location ~ /nchan_redis_cluster_stats$ {
      nchan_redis_upstream_stats my_redis_cluster;
    }
  }

To get the stats, send a GET request to the stats location.

  curl http://localhost/nchan_redis_cluster_stats

The response is JSON of the form:

{
  "upstream": "redis_cluster",
  "nodes": [
    {
      "address"        : "127.0.0.1:7000",
      "id"             : "f13d71b1d14d8bf92b72cebee61421294e95dc72",
      "command_totals" : {
        "connect"    : {
          "msec"     : 357,
          "times"    : 5
        },
        "pubsub_subscribe": {
          "msec"     : 749,
          "times"    : 37
        },
        "pubsub_unsubsribe": {
          "msec"     : 332,
          "times"    : 37
        }
        /*[...]*/
      }
    },
    {
      "address"        : "127.0.0.1:7001",
      "id"             : "b768ecb4152912bed6dc927e8f70284191a79ed7",
      "command_totals" : {
        "connect"    : {
          "msec"     : 4281,
          "times"    : 5
        },
        "pubsub_subscribe": {
          "msec"     : 309,
          "times"    : 33
        },
        "pubsub_unsubsribe": {
          "msec"     : 307,
          "times"    : 30
        },
        /*[...]*/
      },
    }
    /*[...]*/
  ]
}

For brevity, the entire command_totals hash is omitted in this documentation.

related configuration: nchan_redis_upstream_stats, nchan_redis_upstream_stats_disconnected_timeout, nchan_redis_upstream_stats_enabled

Introspection

There are several ways to see what's happening inside Nchan. These are useful for debugging application integration and for measuring performance.

Channel Events

Channel events are messages automatically published by Nchan when certain events occur in a channel. These are very useful for debugging the use of channels. However, they carry a significant performance overhead and should be used during development, and not in production.

Channel events are published to special 'meta' channels associated with normal channels. Here's how to configure them:

location ~ /pubsub/(.+)$ {
  nchan_pubsub;
  nchan_channel_id $1;
  nchan_channel_events_channel_id $1; #enables channel events for this location
}

location ~ /channel_events/(.+) {
  #channel events subscriber location
  nchan_subscriber;
  nchan_channel_group meta; #"meta" is a SPECIAL channel group
  nchan_channel_id $1;
}

Note the /channel_events/... location has a special nchan_channel_group, meta. This group is reserved for accessing "channel events channels", or"metachannels".

Now, say I subscribe to /channel_events/foo I will refer to this as the channel events subscriber.

Let's see what this channel events subscriber receives when I publish messages to

Subscribing to /pubsub/foo produces the channel event

subscriber_enqueue foo

Publishing a message to /pubsub/foo:

channel_publish foo

Unsubscribing from /pubsub/foo:

subscriber_dequeue foo

Deleting /pubsub/foo (with HTTP DELETE /pubsub/foo):

channel_delete foo

The event string itself is configirable with nchan_channel_event_string. By default, it is set to $nchan_channel_event $nchan_channel_id. This string can use any Nginx and Nchan variables.

nchan_stub_status Stats

Like Nginx's stub_status, nchan_stub_status is used to get performance metrics.

  location /nchan_stub_status {
    nchan_stub_status;
  }

Sending a GET request to this location produces the response:

total published messages: 1906
stored messages: 1249
shared memory used: 1824K
channels: 80
subscribers: 90
redis pending commands: 0
redis connected servers: 0
redis unhealthy upstreams: 0
total redis commands sent: 0
total interprocess alerts received: 1059634
interprocess alerts in transit: 0
interprocess queued alerts: 0
total interprocess send delay: 0
total interprocess receive delay: 0
nchan version: 1.1.5

Here's what each line means, and how to interpret it:

Additionally, when there is at least one nchan_stub_status location, this data is also available through variables.

Securing Channels

Securing Publisher Endpoints

Consider the use case of an application where authenticated users each use a private, dedicated channel for live updates. The configuration might look like this:

http {
  server {
    #available only on localhost
    listen  127.0.0.1:8080;
    location ~ /pub/(\w+)$ {
      nchan_publisher;
      nchan_channel_group my_app_group;
      nchan_channel_id $1;
    }
  }

  server {
    #available to the world
    listen 80;

    location ~ /sub/(\w+)$ {
      nchan_subscriber;
      nchan_channel_group my_app_group;
      nchan_channel_id $1;
    }
  }
}

Here, the subscriber endpoint is available on a public-facing port 80, and the publisher endpoint is only available on localhost, so can be accessed only by applications residing on that machine. Another way to limit access to the publisher endpoint is by using the allow/deny settings:

  server {
    #available to the world
    listen 80; 
    location ~ /pub/(\w+)$ {
      allow 127.0.0.1;
      deny all;
      nchan_publisher;
      nchan_channel_group my_app_group;
      nchan_channel_id $1;
    }

Here, only the local IP 127.0.0.1 is allowed to use the publisher location, even though it is defined in a non-localhost server block.

Keeping a Channel Private

A Channel ID that is meant to be private should be treated with the same care as a session ID token. Considering the above use case of one-channel-per-user, how can we ensure that only the authenticated user, and no one else, is able to access his channel?

First, if you intend on securing the channel contents, you must use TLS/SSL:

http {
  server {
    #available only on localhost
    listen  127.0.0.1:8080;
    #...publisher endpoint config
  }
  server {
    #available to the world
    listen 443 ssl;
    #SSL config goes here
    location ~ /sub/(\w+)$ {
      nchan_subscriber;
      nchan_channel_group my_app_group;
      nchan_channel_id $1;
    }
  }
}

Now that you have a secure connection between the subscriber client and the server, you don't need to worry about the channel ID or messages being passively intercepted. This is a minimum requirement for secure message delivery, but it is not sufficient.

You must also take care to do at least one of the following:

Good IDs

An ID that can be guessed is an ID that can be hijacked. If you are not authenticating subscribers (as described below), a channel ID should be impossible to guess. Use at least 128 bits of entropy to generate a random token, associate it with the authenticated user, and share it only with the user's client. Do not reuse tokens, just as you would not reuse session IDs.

X-Accel-Redirect

This feature uses the X-Accel feature of Nginx upstream proxies to perform an internal request to a subscriber endpoint. It allows a subscriber client to be authenticated by your application, and then redirected by nginx internally to a location chosen by your application (such as a publisher or subscriber endpoint). This makes it possible to have securely authenticated clients that are unaware of the channel id they are subscribed to.

Consider the following configuration:

upstream upstream_app {
  server 127.0.0.1:8080;
}

server {
  listen 80; 

  location = /sub_upstream {
    proxy_pass http://upstream_app/subscriber_x_accel_redirect;
    proxy_set_header X-Forwarded-For $remote_addr;
  }

  location ~ /sub/internal/(\w+)$ {
    internal; #this location only accessible for internal nginx redirects
    nchan_subscriber;
    nchan_channel_id $1;
    nchan_channel_group test;
  }
}

As commented, /sub/internal/ is inaccessible from the outside:

> curl  -v  http://127.0.0.1/sub/internal/foo

  < HTTP/1.1 404 Not Found
  < Server: nginx/1.9.5
  <
  <html>
  <head><title>404 Not Found</title></head>
  <body bgcolor="white">
  <center><h1>404 Not Found</h1></center>
  <hr><center>nginx/1.9.5</center>
  </body>
  </html>

But if a request is made to /sub_upstream, it gets forwarded to your application (my_app) on port 8080 with the url /subscriber_x_accel_redirect. Note that you can set any forwarded headers here like any proxy_pass Nginx location, but unlike the case with nchan_authorize_request, Nchan-specific variables are not available.

Now, your application must be set up to handle the request to /subscriber_x_accel_redirect. You should make sure the client is properly authenticated (maybe using a session cookie), and generate an associated channel id. If authentication fails, respond with a normal 403 Forbidden response. You can also pass extra information about the failure in the response body and headers.

If your application successfully authenticates the subscriber request, you now need to instruct Nginx to issue an internal redirect to /sub/internal/my_channel_id. This is accomplished by responding with an empty 200 OK response that includes two headers:

In the presence of these headers, Nginx will not forward your app's response to the client, and instead will internally redirect to /sub/internal/my_channel_id. This will behave as if the client had requested the subscriber endpoint location directly.

Thus using X-Accel-Redirect it is possible to both authenticate all subscribers and keep channel IDs completely hidden from subscribers.

This method is especially useful for EventSource and Websocket subscribers. Long-Polling subscribers will need to be re-authenticated for every new message, which may flood your application with too many authentication requests.

Revoking Channel Authorization

In some cases, you may want to revoke a particular subscriber's authorization for a given channel (e.g., if the user's permissions are changed). If the channel is unique to the subscriber, this is simply accomplished by deleting the channel. The same can be achieved for shared channels by subscribing each subscriber to both the shared channel and a subscriber-specific channel via a multiplexed connection. Deleting the subscriber-specific channel will terminate the subscriber''s connection, thereby also terminating their subscription to the shared channel. Consider the following configuration:

location ~ /sub/(\w+) {
  nchan_subscriber;
  nchan_channel_id shared_$1 user_$arg_userid;
  nchan_authorize_request /authorize;
}

location /pub/user {
  nchan_publisher;
  nchan_channel_id user_$arg_userid;
}

A request to /sub/foo?userid=1234 will subscribe to channels "shared_foo" and "user_1234" via a multiplexed connection. If you later send a DELETE request to /pub/user?userid=1234, this subscriber will be disconnected and therefore unsubscribed from both "user_1234" and "shared_foo".

Variables

Nchan makes several variables usabled in the config file:

Additionally, nchan_stub_status data is also exposed as variables. These are available only when nchan_stub_status is enabled on at least one location:

Configuration Directives

Contact

who's that?

Hello there. I'm Leo, the developer of Nchan.

Do you have questions? A successful large-scale deployment? ..A failing one?
Found a bug? Want to submit a patch? Send money? ...Cake?

Email me at leo@nchan.io, or get in touch with me on github.

Support

15dLBzRS4HLRwCCVjx4emYkxXcyAPmGxM3 If you found Nchan useful, please contribute to help its development.
btc Bitcoin 15dLBzRS4HLRwCCVjx4emYkxXcyAPmGxM3
paypal Paypal

If you need help or support with any aspect of Nchan, consulting services are available.

copy, but don't plagiarise