Bitrix24 Self-hosted administration

At the server side, broadcasting instant messages is backed up by the nginx module: nginx-push-stream-module. This module supports long-polling client connections and ensures message delivery.

When a client opens a page, the former sends an AJAX request to connect to a listening channel on one of the nginx ports: 8893 (http) or 8894 (https). Then, nginx redirects the client to an internal queue server (available only at 127.0.0.1:8895). The server checks the channel for new messages and, if there are none, holds the connection for 40 seconds but does not respond.

If a new message becomes available in the client listening channel within 40 seconds, the server sends it to the client and closes the connection. Otherwise, the server just sends the "304 Not Modified" response to the client and closes the connection.

Once the client has received the server response and the connection is closed, the client can connect again sending the last-modified date and time.

User applications can send messages to the client listening channel by using the Push and Pull module API calls.

It is generally recommended to use HTTPS for push and pull communication.

Configuring the Module

If you use Bitrix Framework distributions with BitrixVA or BitrixEnvironment (for Linux) version 5.0 or better, you won't have to configure anything. If you employ some kind of custom installation, the module configuration will require the following steps.

• Compile nginx enabling nginx-push-stream-module;
  
  

  As an example, use a file from our virtual machine:

  • /etc/nginx/bx/site_enabled/push.conf – the push and pull settings are for publishing messages as well as for operations with the mobile apps;
  • /etc/nginx/bx/conf/im_subscrider.conf – settings for receiving messages;
  • /etc/nginx/bx/conf/im_settings.conf – number of channels, memory size, etc.

• General settings (file /etc/nginx/bx/conf/im_settings.conf):

  # Common settings for nginx-push-stream-module
  push_stream_shared_memory_size 256M;
  push_stream_max_messages_stored_per_channel 1000;
  push_stream_max_channel_id_length 32;
  push_stream_max_number_of_channels 200000;
  push_stream_message_ttl 86400;

• Setting up virtual nginx servers on ports 8893, 8894, 8895 (/etc/nginx/bx/site_enabled/push.conf):

  # support of mobile platforms and for http queries
  server {
      # nginx-push-stream-module server for push & pull
  
  listen 8893;
  server_name _;
  
  # Include error handlers
  include bx/conf/errors.conf;
  
  # Include im subscrider handlers
  include bx/conf/im_subscrider.conf;
  
  location ^~ / { deny all; }
  }
  # support of mobile platforms and for http queries
  # SSL enabled server for reading personal channels
  server {
      listen 8894;
  server_name _;
      include bx/conf/ssl.conf;
  
  # Include error handlers
  include bx/conf/errors.conf;
  
  # Include im subscrider handlers
  include bx/conf/im_subscrider.conf;
  
  location ^~ / { deny all; }
  }
  # for public messages
  # Server to push messages to user channels
  server {
      listen 127.0.0.1:8895;
  server_name _;
  
  location ^~ /bitrix/pub/ {
      push_stream_publisher admin;
      push_stream_channels_path $arg_CHANNEL_ID;
      push_stream_store_messages on;
      allow 127.0.0.0/8;
  deny all;
  }
  
  location ^~ / { deny all; }
  
  # Include error handlers
  include bx/conf/errors.conf;
  }

  To get messages via query to the standard port (80 for http, 443 for https) (/etc/nginx/bx/conf/im_subscrider.conf):

  # Include im subscrider handlers
  include bx/conf/im_subscrider.conf;

  This file contains:

  # Location for long-polling connections
  location ^~ /bitrix/sub {
  
  # we don't use callback and droppped it (XSS)
  if ( $arg_callback ) {
      return 400;
  }
  
      push_stream_subscriber            long-polling;
      push_stream_allowed_origins "*";
      push_stream_channels_path        $arg_CHANNEL_ID;
      push_stream_last_received_message_tag    $arg_tag;
      if ($arg_time) {
          push_stream_last_received_message_time "$arg_time";
      }
      push_stream_longpolling_connection_ttl    40;
      push_stream_authorized_channels_only    on;
      push_stream_message_template '#!NGINXNMS!#{"id":~id~,"channel":"~channel~","tag":"~tag~","time":"~time~","eventid":"~event-id~","text":~text~}#!NGINXNME!#';
  }
  
  # Location for websocet connections
  location ^~ /bitrix/subws/ {
      push_stream_subscriber websocket;
      push_stream_channels_path        $arg_CHANNEL_ID;
      push_stream_websocket_allow_publish    off;
      push_stream_ping_message_interval    40s;
      push_stream_authorized_channels_only     on;
      push_stream_last_received_message_tag    "$arg_tag";
      push_stream_last_received_message_time    "$arg_time";
      push_stream_message_template '#!NGINXNMS!#{"id":~id~,"channel":"~channel~","tag":"~tag~","time":"~time~","eventid":"~event-id~","text":~text~}#!NGINXNME!#';
  }  
  

• General parameters:

  # Common settings for nginx-push-stream-module
  
  push_stream_shared_memory_size			256M;
  push_stream_max_messages_stored_per_channel	1000;
  push_stream_max_channel_id_length		32;
  push_stream_max_number_of_channels		100000;
  push_stream_shared_memory_cleanup_objects_ttl	60;
  push_stream_message_ttl				86400;
  

• Queue server parameters:

  	# Nonsecure server for reading personal channels. Use secure server instead.
  	server {
  		# nginx-push-stream-module server for push & pull
  
  		listen	8893;
  		include	bx/node_host.conf;
  
  		# Include error handlers
  		include	bx/conf/errors.conf;
  
  		# Location for long-polling connections
  		location ^~ /bitrix/sub {
  			push_stream_subscriber			long-polling;
  			set $push_stream_channels_path		$arg_CHANNEL_ID;
  			push_stream_last_received_message_tag	$arg_tag;
  			push_stream_longpolling_connection_ttl	40;
  			push_stream_authorized_channels_only	on;
  			push_stream_content_type		"text/html; charset=utf-8";
  			push_stream_message_template "#!NGINXNMS!#{\"id\":~id~,\"tag\":\"~tag~\",\"time\":\"~time~\",\"text\":~text~}#!NGINXNME!#";
  		}
  
  		# Location for websocet connections
  		location ^~ /bitrix/subws/ {
  			push_stream_websocket;
  			set $push_stream_channels_path		$arg_CHANNEL_ID;
  			push_stream_websocket_allow_publish	off;
  			push_stream_ping_message_interval	40s;
  			push_stream_authorized_channels_only on;
  			push_stream_message_template		"#!NGINXNMS!#{\"id\":~id~,\"tag\":\"~tag~\",\"time\":\"~time~\",\"text\":~text~}#!NGINXNME!#";
  		}
  
  		location ^~ / 			{ deny all; }
  	}
  
  	# SSL enabled server for reading personal channels
  	server {
  		listen	8894;
  		include	bx/node_host.conf;
  		include	bx/conf/ssl.conf;
  
  		# Include error handlers
  		include	bx/conf/errors.conf;
  
  		add_header "Access-Control-Allow-Origin" "*";
  		add_header "Access-Control-Allow-Headers" "if-modified-since, origin, if-none-match";
  
  		# Location for long-polling connections
  		location ^~ /bitrix/sub {
  			push_stream_subscriber			long-polling;
  			set $push_stream_channels_path		$arg_CHANNEL_ID;
  			push_stream_last_received_message_tag	$arg_tag;
  			push_stream_longpolling_connection_ttl	40;
  			push_stream_authorized_channels_only	on;
  			push_stream_content_type		"text/html; charset=utf-8";
  			push_stream_message_template		"#!NGINXNMS!#{\"id\":~id~,\"tag\":\"~tag~\",\"time\":\"~time~\",\"text\":~text~}#!NGINXNME!#";
  		}
  
  		# Location for web socket connections
  		location ^~ /bitrix/subws/ {
  			push_stream_websocket;
  			set $push_stream_channels_path		$arg_CHANNEL_ID;
  			push_stream_websocket_allow_publish	off;
  			push_stream_ping_message_interval	40s;
  			push_stream_authorized_channels_only	on;
  			push_stream_message_template		"#!NGINXNMS!#{\"id\":~id~,\"tag\":\"~tag~\",\"time\":\"~time~\",\"text\":~text~}#!NGINXNME!#";
  		}
  
  		location ^~ / 			{ deny all; }
  	}
  
  	# Server to push messages to user channels
  	server {
  		listen 127.0.0.1:8895;
  		include	bx/node_host.conf;
  
  		location ^~ /bitrix/pub/ {
  			push_stream_publisher			admin;
  			set $push_stream_channel_id		$arg_CHANNEL_ID;
  			push_stream_store_messages		on;
  			push_stream_keepalive			off;
  			allow					127.0.0.0/8;
  			deny					all;
  		}
  
  		location ^~ /	{ deny all; }
  
  		# Include error handlers
  		include	bx/conf/errors.conf;
  	}

XMLHttpRequest cannot load 
http://example.com:8893/bitrix/sub/?CHANNEL_ID=<уникальный_адрес_канала>&tag=1&rnd=1380619831146. 
Origin http://example.com is not allowed by Access-Control-Allow-Origin.

add_header "Access-Control-Allow-Origin" "*";
add_header "Access-Control-Allow-Headers" "if-modified-since, origin, if-none-match";