Plugin-Based Integration Guide (OpenResty)
💡 Note:
This guide is intended for sites utilizing OpenResty as a reverse proxy server and integrating with River Cloud via plugin installation. For alternative integration methods, please revert to the Integration Guide to select the appropriate documentation; for local, private deployment of River Cloud services and plugin-based integration, proceed to the Private Deployment Guide.
The content below primarily illustrates the deployment of OpenResty on a Debian distribution of the Linux operating system. For non-Debian Linux distributions running OpenResty, all sections except "3.1 Installation Using Precompiled Packages" can serve as a reference.
Currently, user sites with Content-Security-Policy (CSP) in the HTTP response headers are not supported. If such sites require River Cloud integration, please disable this response header first. (For an overview of the plugin-based integration principle, refer to Introduction to Integration Principles)
1 Site Creation and Information Saving
- First, log in to the River Cloud Management Interface using a tenant account registered on River Cloud or Huawei Cloud. Click Platform at the bottom of the left navigation bar, then enter the Account Management tab, as shown below. Copy the Enterprise ID number for later use.
💡 Tip:
A tenant refers to an account registered through the River Cloud login interface or via Huawei Cloud. This account possesses irrevocable administrator privileges, enabling the creation of new administrators and the modification of their permissions, resetting passwords, and deleting accounts.
- Navigate to Configuration Management > Site Management. Copy and save the Access Key under the Global Configuration tab for subsequent use.
- Click Add Site at the top left of the page to enter the new site configuration interface.
Refer to the content in the User Manual > 3.1 Site Management section for configuring a new site (if the client of the site is a WeChat mini-program, remember to select WeChat Mini-Program Protection during configuration), and note down the domain name filled in for later use.
💡 Attention:
Ensure that the domain name entered here matches the value of the server_name directive in the OpenResty configuration file.
For cases where the server_name directive in the OpenResty configuration file uses regular expressions, also refer to the content in Appendix 2.
2 Plugin Download
After purchasing the service (accounts without a service purchase are only eligible for a one-month trial period. Refer to How to Obtain a River Cloud Account for purchase methods), log in to the River Cloud Management Interface using the received account, and download the plugin installation file rskeeper_xxx.tar.gz to your local system via the Plugin button (as shown below) on the Configuration Management > Site Management page.
Copy the file to the operating system where OpenResty is installed in preparation for installation.
3 Plugin Installation
First, ensure that OpenResty is properly installed on your system, following the Official Installation Instructions.
Run the following command to extract the file.
tar -xvf rskeeper_xxx.tar.gz
After extraction, you will obtain a precompiled file named similar to rskeeper_VERSION_NUMBER-xxxx_amd64.deb, and a source code file named similar to rskeeper_VERSION_NUMBER_xxxx_source.tgz.
💡 Tip:
For non-Debian distributions, please use the source package for installation.
3.1
Installation Using Precompiled Package
Execute the following command to complete the installation.
dpkg -i rskeeper_VERSION_NUMBER-xxxx_amd64.deb
3.2 Installation Using Source Package
Ensure that the gcc compiler suite and make tool are installed in your environment, and that the Lua library header files are present in the following path:
openresty/luajit/include/luajit-2.1/
Execute the following commands to complete the installation.
tar -zvxf rskeeper_VERSION_NUMBER_xxxx_source.tgz
cp -r riversec /usr/local/openresty/lualib
💡 Tip:
The default installation path for OpenResty is /usr/local/openresty/. If your actual installation path differs, such as /apt/openresty/, you will need to replace the above path /usr/local/openresty/ with /apt/openresty/.
4 Configuring the OpenResty Server
Configuring the OpenResty
server involves three steps:
❶ Backup and modify the server configuration file.
❷ Modify the plugin configuration file.
❸Restart OpenResty.
Additionally, to cater to different protection needs, these three steps can be adjusted to implement two protection modes: Asynchronous Mode and Synchronous Mode.
Asynchronous Mode: In this mode, the plugin forwards the business request before receiving the detection result from River Cloud for that request. Upon receiving the result, it then processes subsequent requests from that client based on the current site's operational mode.
This mode is suitable for scenarios where the timing of interception is not extremely critical, allowing a small number of abnormal requests to access the server, but where high speed in gateway forwarding is essential.
💡 Tip:
If you have not purchased the rule module, it is recommended to use the asynchronous mode.
Synchronous Mode: Here, the plugin temporarily holds the request until it receives the detection result from River Cloud. Based on the site's current operational mode, it then processes that request and any subsequent requests from the same client.
This mode is appropriate for scenarios where a slight decrease in gateway forwarding speed is acceptable, but strict timing of interception is crucial, and no abnormal requests are allowed to access the server.
The following sections will detail the configuration for both modes.
4.1 Asynchronous Mode Configuration
4.1.1 Backup and Modify Server Configuration File
First, backup the original OpenResty configuration file to restore it if needed later.
💡 Tip:
The default installation path for OpenResty, where its configuration file is located, is /usr/local/openresty/nginx/conf/nginx.conf. If your actual installation path differs, such as /apt/openresty/, replace /usr/local/openresty/ with your actual path.
Assuming the original OpenResty configuration file is as follows.
# Protecting the root path under website1.com
worker_processes auto;
error_log logs/error.log error;
events {
worker_connections 1024;
}
http {
include mime.types;
default_type application/octet-stream;
sendfile on;
keepalive_timeout 65;
###########################
###### Insert Directive Set 1 here ######
###########################
server {
listen 80;
server_name website1.com;
#########################################################
###### Ensure the server_name domain matches the domain entered when creating a new site ######
#########################################################
location / {
###########################
###### Insert Directive Set 2 here ######
###########################
proxy_pass http://10.10.71.143:9090;
}
}
server {
listen 82;
server_name website2.com;
location / {
proxy_pass http://10.10.71.143:8080;
}
}
}
To protect the path location / for the site website1.com, three modifications are needed in the original configuration file:
Add Directive Set 1 under the http configuration block.
Add Directive Set 2 under the server > location / configuration block.
Ensure the server_name within the server configuration block matches the domain name entered in the River Cloud configuration interface when creating a new site.
The configuration file with inserted directive sets is shown below.
💡 Note:
Each directive set includes instructions that need modification, as indicated by the comments below them. Please make the necessary changes accordingly.
worker_processes auto;
error_log logs/error.log error;
events {
worker_connections 1024;
}
http {
include mime.types;
default_type application/octet-stream;
sendfile on;
keepalive_timeout 65;
1️⃣ ###### Directive Set 1 Start: Remember to specify a valid DNS address!!!
resolver 114.114.114.114 ipv6=off;
# Specify a valid DNS address for OpenResty. 114.114.114.114 is a commonly used DNS in China. Modify as needed.
# If a DNS is already configured in the original file, you can comment out this line. However, ensure the existing DNS server can resolve detector.riveryun.com.
include /usr/local/openresty/lualib/riversec/conf/sync/init.conf;
# The default installation path for OpenResty is /usr/local/openresty/. If your actual installation path differs, such as /apt/openresty/, replace /usr/local/openresty/ with your actual path. Also, replace /usr/local/openresty/ in the init.conf file with your actual path.
1️⃣ ###### Directive Set 1 End
server {
listen 80;
server_name website1.com;
#########################################################
###### Ensure the server_name domain matches the domain entered when creating a new site ######
#########################################################
2️⃣ ###### Directive Set 2 Start
include /usr/local/openresty/lualib/riversec/conf/sync/detect.conf;
2️⃣ ###### Directive Set 2 End
location / {
3️⃣ ###### Directive Set 3 Start
include /usr/local/openresty/lualib/riversec/conf/sync/guard.conf;
# The default installation path for OpenResty is /usr/local/openresty/. If your actual installation path differs, such as /apt/openresty/, replace /usr/local/openresty/ with your actual path. Also, replace /usr/local/openresty/ in the guard.conf file with your actual path.
3️⃣ ###### Directive Set 3 End
proxy_pass http://10.10.71.143:9090;
}
}
server {
listen 82;
server_name website2.com;
location / {
proxy_pass http://10.10.71.143:8080;
}
}
}
4.1.2 Modify the Plugin Configuration File
The path to the plugin configuration file is /usr/local/openresty/lualib/riversec/static/config.json. Please modify it using the information previously copied, as follows:
{
"module": "guard",
"company": "riversec",
"version": "VERSION_NUMBER",
"build": "6e6c503",
"keeper_id": "keeper_GATEWAY_IP",
"tenant_id": "default_tenant", #### Modify to the Enterprise ID copied in Section 1 ####
"access_key": "default_access_key", #### Modify to the Access Key copied in Section 1 ####
"endpoint_url": "https://detector.BASE_DOMAIN/4h2uWW2S/",
"enable": true,
"http": {
"interval_in_seconds": 3,
"max_retry": 3,
"connect_timeout_ms": 500,
"send_timeout_ms": 500,
"read_timeout_ms": 500
}
}
4.1.3 Restart OpenResty
After completing the above configurations, execute systemctl restart openresty or openresty -s reload to restart OpenResty, thereby enabling integration
with River Cloud.
💡 Tip:
For cases where the server_name directive in the OpenResty configuration file uses regular expressions, please refer to Appendix 2 for guidance.
4.2 Synchronous Mode Configuration
4.2.1 Backup and Modify Server Configuration File
Initially, backup the existing OpenResty configuration file for potential future restoration.
💡 Tip:
The official default installation path for OpenResty, where its configuration file is located, is /usr/local/openresty/nginx/conf/nginx.conf. If your actual installation path differs, such as /apt/openresty/, you should replace /usr/local/openresty/ with /apt/openresty/.
Assuming the original OpenResty configuration file is as follows:
# Protecting the root path under website1.com
worker_processes auto;
error_log logs/error.log error;
events {
worker_connections 1024;
}
http {
include mime.types;
default_type application/octet-stream;
sendfile on;
keepalive_timeout 65;
###########################
###### Insert Directive Set 1 here ######
###########################
server {
listen 80;
server_name website1.com;
#########################################################
###### Ensure the server_name domain matches the domain entered when creating a new site ######
#########################################################
###########################
###### Insert Directive Set 2 here ######
###########################
location / {
###########################
###### Insert Directive Set 3 here ######
###########################
proxy_pass http://10.10.71.143:9090;
}
}
server {
listen 82;
server_name website2.com;
location / {
proxy_pass http://10.10
Set 2 End
location / {
3️⃣ ###### Directive Set 3 Start
include /usr/local/openresty/lualib/riversec/conf/sync/guard.conf;
# The official default installation path for OpenResty is /usr/local/openresty/. If your actual installation path differs, such as /apt/openresty/, replace /usr/local/openresty/ with your actual path. Also, replace /usr/local/openresty/ in the guard.conf file with your actual path.
3️⃣ ###### Directive Set 3 End
proxy_pass http://10.10.71.143:9090;
}
}
server {
listen 82;
server_name website2.com;
location / {
proxy_pass http://10.10.71.143:8080;
}
}
}
4.2.2 Modify the Plugin Configuration File
The plugin configuration file is located at /usr/local/openresty/lualib/riversec/static/config.json. Please modify it using the information previously copied, as follows:
💡 Note:
The plugin supports both synchronous and asynchronous modes. Be sure to choose the appropriate mode based on the configuration example below.
{
"module": "guard",
"company": "riversec",
"version": "VERSION_NUMBER",
"build": "6e6c503",
"keeper_id": "keeper_GATEWAY_IP",
"tenant_id": "default_tenant", #### Modify to the Enterprise ID copied in Section 1 ####
"access_key": "default_access_key", #### Modify to the Access Key copied in Section 1 ####
"sync": "true", #### Add this configuration. ####
"endpoint_url": "https://detector.BASE_DOMAIN/4h2uWW2S/",
"enable": true,
"http": {
"interval_in_seconds": 3,
"max_retry": 3,
"connect_timeout_ms": 500,
"send_timeout_ms": 500,
"read_timeout_ms": 500
}
}
4.2.3 Restart OpenResty
After completing the above configurations, execute systemctl restart openresty or openresty -s reload to restart OpenResty, thereby enabling integration with River Cloud.
💡 Tip:
For cases where the server_name directive in the OpenResty configuration file uses regular expressions, please refer to Appendix 2
5 Verifying Integration
💡 Tip:
The following content describes the verification method for Web site integration. For the protection of WeChat mini-program businesses, it is necessary to first integrate River Cloud's SDK package into the mini-program for successful integration. Please consult River Information Limited Company for WeChat mini-program integration business through the information on the Contact Us page.
To verify that the site has successfully integrated with River Cloud, first visit the site's domain name through a browser. Then, validate using the following two methods. If the observed phenomena match the descriptions of these two methods, it indicates that the site has successfully completed integration.
Method 1: In the browser's developer tools (opened by pressing F12), confirm that the site contains cookies named zVZq and PpaP.
Method 2: Log in to the River Cloud Management Interface. In the Configuration Management > Site Management page, under the Configuration Status section, verify that the plugin name keeper_GATEWAY_IP is displayed as a green-background tag (hover over the name to view the full name), as shown in the image below.
💡 Tip:
The "Configuration Status" name displayed in Method 2 is the default name of the plugin. When it appears as a green tag, it indicates that the plugin installed on the current OpenResty is functioning normally. This name can be changed as needed, for example, to the IP address of the current OpenResty server, indicating that the plugin is running on that server. For modification methods, please read Appendix 1 Plugin Configuration Items.
6 Manual Escape
Method One
In urgent situations, you can modify the plugin configuration file at /usr/local/openresty/lualib/riversec/static/config.json to bypass the plugin and directly forward traffic to the backend server, ensuring the continuity of business traffic.
💡 Tip:
The official default installation path for OpenResty is /usr/local/openresty/. If your actual installation path differs, such as /apt/openresty/, you need to replace /usr/local/openresty/ with /apt/openresty/.
Open the configuration file, then set the top-level "enable" key to false and save. Afterward, reload the configuration by executing the openresty -s reload command to achieve a manual escape. As shown below:
{
"module": "guard",
"company": "riversec",
"version": "VERSION_NUMBER",
"build": "6e6c503",
"keeper_id": "keeper_GATEWAY_IP",
"tenant_id": "your Enterprise ID",
"access_key": "your Access Key",
"endpoint_url": "https://detector.BASE_DOMAIN/4h2uWW2S/",
"enable": false, #### Set to false for manual escape ####
"http": {
"interval_in_seconds": 3,
"max_retry": 3,
"connect_timeout_ms": 500,
"send_timeout_ms": 500,
"read_timeout_ms": 500
}
}
Method Two
Apart from modifying the plugin's configuration file for escape, you can also achieve the same effect by commenting out the following lines in the OpenResty configuration file at /usr/local/openresty/nginx/conf/nginx.conf.
💡 Tip:
The official default installation path for OpenResty is /usr/local/openresty/. If your actual installation path differs, such as /apt/openresty/, you need to replace /usr/local/openresty/ with /apt/openresty/.
# For asynchronous mode, comment out these two lines added in the OpenResty configuration file
# include /usr/local/openresty/lualib/riversec/conf/init.conf;
# include /usr/local/openresty/lual
ib/riversec/conf/guard.conf;
# For synchronous mode, comment out these three lines added in the OpenResty configuration file
# include /usr/local/openresty/lualib/riversec/conf/sync/init.conf;
# include /usr/local/openresty/lualib/riversec/conf/sync/guard.conf;
# include /usr/local/openresty/lualib/riversec/conf/sync/detect.conf;
After commenting out the relevant lines, reload the configuration by executing the openresty -s reload command to achieve a manual escape.
Appendix 1 Plugin Configuration Items
After installing the plugin, a dedicated configuration file (/usr/local/openresty/lualib/riversec/static/config.json) is generated. Typically, the default configuration is effective and does not require further modification.
💡 Tip:
The official default installation path for OpenResty is /usr/local/openresty/. If your actual installation path differs, such as /apt/openresty/, you need to replace /usr/local/openresty/ with /apt/openresty/.
However, if you need to change the plugin's name, disable the plugin for manual escape (refer to Manual Escape > Method One), or perform other operations, you can do so by modifying the configuration items in this JSON file.
Changing the Plugin Name
Once the plugin successfully connects with River Cloud, the plugin name (the value of "keeper_id" below) will be displayed in the Configuration Management > Site Management page of the River Cloud Management Interface, under the Configuration Status section, as a green-background tag.
Therefore, it is recommended to modify the "keeper_id" value in the /usr/local/openresty/lualib/riversec/static/config.json file to an easily understandable string, such as the name or IP address of the current OpenResty server (assuming it is 10.0.0.1), as shown below:
{
"module": "guard",
"company": "riversec",
"version": "VERSION_NUMBER",
"build": "6e6c503",
"keeper_id": "10.0.0.1", #### Modify to the name or address of the server where the plugin is located, to be displayed in the River Cloud Management Interface ####
"tenant_id": "your Enterprise ID",
"access_key": "your Access Key",
"endpoint_url": "https://detector.BASE_DOMAIN/4h2uWW2S/",
"enable": true,
"http": {
"interval_in_seconds": 3,
"max_retry": 3,
"connect_timeout_ms": 500,
"send_timeout_ms": 500,
"read_timeout_ms": 500
}
}
After saving, reload the configuration by executing the openresty -s reload command. Visit the site through a browser, and within 2-3 seconds, it should take effect. Then, log in to the River Cloud Management Interface, enter the Configuration Management > Site Management page, and you will see the name displayed as a green-background tag in the Configuration Status section.
Configuration Item List
The following list includes explanations of the main configuration items in the config.json file.
enable: Whether to enable all functions under the
entire module, can be set to true or false, with the default being true.
keeper_id: Identifies the plugin that successfully connects to the site, default is revol_keeper_default.
tenant_id: Your tenant ID number, which is the Enterprise ID obtained in Section 1 Creating Site and Saving Information.
💡 Tip:
A tenant refers to an account registered through the River Cloud login interface or via Huawei Cloud. This account has irrevocable administrative privileges, capable of creating new administrators and modifying their permissions, resetting passwords, and deleting accounts.
access_key: Your exclusive access code.
http.interval_in_seconds: Sets the interval for health checks against the River detection service (in seconds), default is 3. (Also refer to Issue 1 in Known Issues)
http.max_retry: Sets the number of retries for health checks against the River detection service. If the service fails to respond normally for a number of times exceeding this number, the detection service is considered unavailable, and the plugin functionality is immediately disabled, default is 3.
http.connect_timeout_ms: Connection timeout setting for health checks, default value is 500ms, see openresty lua sock for details.
http.send_timeout_ms: Send timeout setting for health checks, default value is 500ms.
http.read_timeout_ms: Receive timeout setting for health checks, default value is 500ms.
Appendix 2 Configuration Method for server_name in OpenResty Configuration File as Regular Expression
For cases where the server_name directive in the OpenResty configuration file uses regular expressions, corresponding modifications to the /usr/local/openresty/lualib/riversec/static/config.json file are necessary for correct integration.
For example, if the OpenResty configuration file contains the following configuration:
server_name ~^(www\.)?(.+)(\.riveryun\.com)?$;
And the domain name entered when creating a new site on River Cloud is www.mysite.riveryun.com, then the following field needs to be added to the config.json file to enable River Cloud to successfully match the domain name filled in the site, thus achieving integration with the plugin.
"hosts": [
{ "server_name": "~^(www\.)?(.+)(\.riveryun\.com)?$",
"alias": "www.mysite.riveryun.com" }
],
After adding the field, the example configuration would be as follows. Execute openresty -s reload to activate the changes.
{
"module": "guard",
"company": "riversec",
"version": "VERSION_NUMBER",
"build": "6e6c503",
"keeper_id": "keeper_GATEWAY_IP",
"tenant_id": "default_tenant", #### Modify to the previously copied Enterprise ID ####
"access_key": "default_access_key", #### Modify to the previously copied Access Key ####
"endpoint_url": "https://detector.BASE_DOMAIN/4h2uWW2S/",
"enable": true,
"hosts": [
{ "server_name": "~^(www\.)?(.+)(\.riveryun\.com)?$",
"alias": "www.mysite.riveryun.com"}
],
"http": {
"interval_in_seconds": 3,
"max_retry": 3,
"connect_timeout_ms": 500,
"send_timeout_ms": 500,
"read_timeout_ms": 500
}
}
Appendix 3 Uninstalling the Plugin
Method One:
Uninstall the plugin on the OpenResty server by executing the rm command to delete the riversec directory.
Execute the rm command to uninstall the plugin:
rm -rf /usr/local/openresty/lualib/riversecReplace the current OpenResty configuration file with the one you previously backed up.
Then, restart OpenResty with the following command:
systemctl restart openresty
or
openresty -s reloadLog in to the River Cloud Management Interface. In the Configuration Management > Site Management page, the plugin tag under the Configuration Status section will turn orange, indicating that the plugin has disconnected. If you can open the site page through a browser, it means the uninstallation has been successful, and the site has returned to its state before installation.
💡 Tip:
The official default installation path for OpenResty is /usr/local/openresty/. If your actual installation path differs, such as /apt/openresty/, replace /usr/local/openresty/ with /apt/openresty/.
Method Two:
Uninstall the plugin installed on the OpenResty server by executing the dpkg command.
Execute the dpkg command to uninstall the plugin:
dpkg -r rskeeperReplace the current OpenResty configuration file with the one you previously backed up.
Then, restart OpenResty with the following command:
systemctl restart openresty
or
openresty -s reloadLog in to the River Cloud Management Interface. In the Configuration Management > Site Management page, the plugin tag under the Configuration Status section will turn orange, indicating that the plugin has disconnected. If you can open the site page through a browser, it means the uninstallation has been successful, and the site has returned to its state before installation.