Bitrix24 Self-hosted For Advanced Users

The Push and Pull module is used to broadcast messages and notifications to website clients. Because this feature is implemented as a stand-alone module, any other module, standard or custom, can send messages to clients using the module API calls.

This module is imperative for fully functional operation of the modules Mobile Application, Blogs and Web Messenger.

The module is built around the following technologies.

Pull technology is an efficient and low cost method of having a message broadcasted to multiple unknown recipients. It is mostly beneficial to clients looking up for a specific item of data. At present, pull requests form the foundation of network computing where multitudes of clients request data from central servers. An example of application of this kind of network communication is HTTP requests responded to by the websites.

Push is in some sense contrast to pull technology.

A user may subscribe to receive information from a content provider and then have information "pushed" to their computer or mobile device every time such information is available at the server.

How Push and Pull Work?

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 BitrixVM 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, a file from our virtual machine can be used:

  • /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.
  
  

  Parameters for nginx-push-stream-module version 0.4.0 (recommended)

  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 through a query on 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!#'; }

  
  

  Parameters for nginx-push-stream-module version 0.3.4

  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; }

  
  
• Open Settings > System Settings > Module Settings > Push and Pull and enable the option "nginx-push-stream-module is installed on server":

  

  Select the virtual machine version you are using. The recommended version is 4.4 or higher because it includes a newer version of nginx-push-stream-module (0.4.0) which enables web sockets and command sending.

• When setting the value of Maximum number of commands to send while connected to server, remember that it depends on nginx's large_client_header_buffers parameter. When the latter is set to 8 KB, the maximum number of commands is 100. These two values are directly proportional; if your requirement is to send 200 commands while connected, set large_client_header_buffers to 16 KB. In general, the more the average number of possible message recipients, the more the value of Maximum number of commands to send… field should be. While this parameter is directly related to the total intranet users, you will have to find the value that suits your conditions best experimentally. If you have powerful hardware, you could just allow an ample load margin and be on the safe side: use 100 command for 150 users, 200 commands for 300 users and so on.
• Override the URL templates if so required. For multiple domain configurations, use #DOMAIN# macro as the domain name in the message view URL: it will be replaced with an appropriate domain name automatically. Example: http://#DOMAIN#:8893/bitrix/sub/
  Note: If your configuration of nginx-push-stream-module is similar to that of BitrixEnvironment, you won't have to edit these URL's.

• If you intend to communicate with mobile devices, check the option Send PUSH notifications to mobile devices.
• If the system manages multiple active sites, you can enable or disable the module for each site individually.

XMLHttpRequest cannot load http://example.com:8893/bitrix/sub/?CHANNEL_ID=123a27000bed7ee1ffd6935e063df0cf/c15e31dfc968de41b032474d8d651b77&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";