Views: 21761
Last Modified: 26.06.2015
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 (or client pull) is a style of network
communication where the initial request for data originates from the client,
and then is responded to by the server.
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.
Push (or server push) is a style of
Internet-based communication where the request for a transaction is initiated
by the publishing server according to the client parameters.
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.
Note: Bitrix Framework is capable of providing
considerably high messaging rate without nginx-push-stream-module: max.
interval of 60 seconds, which reduces to 10 seconds if there are pending
messages.
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.
Note: The time at the server must be consistent.
Perform time synchronization regularly to ensure correct channel status.
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.
Note: The example provided below is given only as a sample. The configuration of a web project not based on either the BitrixVM or BitrixEnvironment is the sole responsibility of the project’s administrator.
- 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.
Note: the module supports web sockets since version 14.1.2. This option is only available if a corresponding parameter is enabled in nginx-push-stream-module.
Attention! If you get an error like
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.
your
push-stream-module version is below 0.3.4.
To eliminate the error, please update the module or comment out the following lines:
add_header "Access-Control-Allow-Origin" "*";
add_header "Access-Control-Allow-Headers" "if-modified-since, origin, if-none-match";