Mirror
/
Tengine
mirror of https://github.com/alibaba/tengine.git
1
0
Fork 0
Code Issues Releases Wiki Activity
Browse Source

updated ngx_http_dyups_module.md.

pull/1281/head
Xiaochen Wang 6 years ago
committed by sky
parent
b3a69db86e
commit
9724234916
1 changed files with 111 additions and 78 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 189
      docs/modules/ngx_http_dyups_module.md

189
docs/modules/ngx_http_dyups_module.md
View File

@ -1,26 +1,13 @@
Name
====
* ngx_http_dyups_module
Description
===========
## Description
This module can be used to update your upstream-list without reloadding Nginx.
Compilation
===========
The module is not compiled into Tengine by default. It can be enabled with '--with-http_dyups_module'
configuration parameter, and enabled lua support with '--with-http_dyups_lua_api'.
But it can not be compiled as a '.so'.
Example
==========
## Example
file: conf/nginx.conf
`ATTENTION`: You MUST use nginx variable to do proxy_pass
daemon off;
error_log logs/error.log debug;
@ -29,29 +16,28 @@ file: conf/nginx.conf
http {
dyups_upstream_conf conf/upstream.conf;
include conf/upstream.conf;
server {
listen 8080;
location / {
proxy_pass http://$host;
# The upstream here must be a nginx variable
proxy_pass http://$host;
}
}
server {
listen 8088;
location / {
echo 8088;
return 200 "8088";
}
}
server {
listen 8089;
location / {
echo 8089;
return 200 "8089";
}
}
@ -63,6 +49,16 @@ file: conf/nginx.conf
}
}
If your original config looks like this:
proxy_pass http://upstream_name;
please replace it with:
set $ups upstream_name;
proxy_pass http://$ups;
`$ups` can be any valid nginx variable.
file: conf/upstream.conf
@ -75,85 +71,112 @@ file: conf/upstream.conf
}
Directives
===========
## Installation
* Only install dyups module
dyups_interface
--------------------------
```bash
# to compile as a static module
$ ./configure --add-module=./modules/ngx_http_dyups_module
# to compile as a dynamic module
$ ./configure --add-dynamic-module=./modules/ngx_http_dyups_module
```
* Install dyups module with lua-nginx-module and upstream check module
* upstream check module: To make upstream check module work well with dyups module, you should use `./modules/ngx_http_upstream_check_module`.
* lua-nginx-module: To enable [dyups LUA API](#lua-api-example), you MUST put `--add-module=./modules/ngx_http_lua_module` in front of `--add-module=./modules/ngx_http_dyups_module` in the `./configure` command.
```bash
# to compile as a static module
$ ./configure --add-module=./modules/nginx_upstream_check_module --add-module=./modules/lua-nginx-module --add-module=./modules/ngx_http_dyups_module
```
**Syntax**: *dyups_interface*
## Directives
**Default**: *none*
### dyups_interface
**Context**: *loc*
Syntax: **dyups_interface**
Default: `none`
Context: `loc`
This directive set the interface location where you can add or delete the upstream list. See the section of Interface for detail.
dyups_read_msg_timeout
-----------------------------
**Syntax**: *dyups_read_msg_timeout time*
### dyups_read_msg_timeout
Syntax: **dyups_read_msg_timeout** `time`
**Default**: *1s*
Default: `1s`
**Context**: *main*
Context: `main`
This directive set the interval of workers readding the commands from share memory.
dyups_shm_zone_size
-----------------------------
**Syntax**: *dyups_shm_zone_size size*
### dyups_shm_zone_size
**Default**: *2M*
Syntax: **dyups_shm_zone_size** `size`
**Context**: *main*
Default: `2MB`
Context: `main`
This directive set the size of share memory which used to store the commands.
dyups_upstream_conf
-----------------------------
**Syntax**: *dyups_upstream_conf path*
### dyups_upstream_conf
Syntax: **dyups_upstream_conf** `path`
**Default**: *none*
Default: `none`
**Context**: *main*
Context: `main`
This directive set the path of file which you dumped all of upstreams' configs, it will be loaded in `init process` after process respwan to restore upstreams.
This directive has been deprecated
dyups_trylock
-----------------------------
**Syntax**: *dyups_trylock on | off*
### dyups_trylock
**Default**: *off*
Syntax: **dyups_trylock** `on | off`
**Context**: *main*
Default: `off`
Context: `main`
You will get a better prefomance but it maybe not stable, and you will get a '409' when the update request conflicts with others.
restful interface
========================
### dyups_read_msg_log
Syntax: **dyups_read_msg_log** `on | off`
Default: `off`
Context: `main`
GET
-------------------
You can enable / disable log of workers readding the commands from share memory. The log looks like:
* `/detail` get all upstreams and their servers
* `/list` get the list of upstreams
* `/upstream/name` find the upstream by it's name
```
2017/02/28 15:37:53 [info] 56806#0: [dyups] has 0 upstreams, 1 static, 0 deleted, all 1
```
## restful interface
POST
-------------------
### GET
- `/detail` get all upstreams and their servers
- `/list` get the list of upstreams
- `/upstream/name` find the upstream by it's name
* `/upstream/name` update one upstream
* `body` commands;
* `body` server ip:port;
### POST
- `/upstream/name` update one upstream
- `body` commands;
- `body` server ip:port;
DELETE
-------------------
* `/upstream/name` delete one upstream
### DELETE
- `/upstream/name` delete one upstream
Call the interface, when you get the return code is `HTTP_INTERNAL_SERVER_ERROR 500`, you need to reload nginx to make the Nginx work at a good state.
@ -163,10 +186,10 @@ The /list and /detail interface will return `HTTP_NO_CONTENT 204` when there is
Other code means you should modify your commands and call the interface again.
`ATTENEION`: You also need a `third-party` to generate the new config and dump it to Nginx'conf directory.
`ATTENTION`: You also need a `third-party` to generate the new config and dump it to Nginx'conf directory.
### Sample
Sample
-------------------
```bash
» curl -H "host: dyhost" 127.0.0.1:8080
<html>
@ -188,34 +211,37 @@ success
» curl 127.0.0.1:8081/detail
host1
server 127.0.0.1:8088
server 127.0.0.1:8088 weight=1 max_conns=0 max_fails=1 fail_timeout=10 backup=0 down=0
host2
server 127.0.0.1:8089
server 127.0.0.1:8089 weight=1 max_conns=0 max_fails=1 fail_timeout=10 backup=0 down=0
dyhost
server 127.0.0.1:8089
server 127.0.0.1:8088
server 127.0.0.1:8089 weight=1 max_conns=0 max_fails=1 fail_timeout=10 backup=0 down=0
server 127.0.0.1:8088 weight=1 max_conns=0 max_fails=1 fail_timeout=10 backup=0 down=0
» curl -i -X DELETE 127.0.0.1:8081/upstream/dyhost
success
» curl 127.0.0.1:8081/detail
host1
server 127.0.0.1:8088
server 127.0.0.1:8088 weight=1 max_conns=0 max_fails=1 fail_timeout=10 backup=0 down=0
host2
server 127.0.0.1:8089
server 127.0.0.1:8089 weight=1 max_conns=0 max_fails=1 fail_timeout=10 backup=0 down=0
```
API
========================
## C API
```c
extern ngx_flag_t ngx_http_dyups_api_enable;
ngx_int_t ngx_dyups_update_upstream(ngx_str_t *name, ngx_buf_t *buf,
ngx_str_t *rv);
ngx_int_t ngx_dyups_delete_upstream(ngx_str_t *name, ngx_str_t *rv);
extern ngx_dyups_add_upstream_filter_pt ngx_dyups_add_upstream_top_filter;
extern ngx_dyups_del_upstream_filter_pt ngx_dyups_del_upstream_top_filter;
```
## Lua API Example
@ -229,14 +255,14 @@ content_by_lua '
local status, rv = dyups.update("test", [[server 127.0.0.1:8088;]]);
ngx.print(status, rv)
if status ~= 200 then
if status ~= ngx.HTTP_OK then
ngx.print(status, rv)
return
end
ngx.print("update success")
status, rv = dyups.delete("test")
if status ~= 200 then
if status ~= ngx.HTTP_OK then
ngx.print(status, rv)
return
end
@ -244,3 +270,10 @@ content_by_lua '
';
```
## Compatibility
### Module Compatibility
* [lua-upstream-nginx-module](https://github.com/agentzh/lua-upstream-nginx-module): You can use `lua-upstream-nginx-module` to get more detail infomation of upstream.
* [upstream check module](http://tengine.taobao.org/document/http_upstream_check.html): To make upstream check module work well with dyups module, you should use `./modules/ngx_http_upstream_check_module`.
Write Preview
Loading…
Cancel
Save