xref: /f-stack/doc/F-Stack_Nginx_APP_Guide.md (revision 08dba010) 
1# F-Stack Nginx APP Guide
2
3F-Stack is an open source network framework based on DPDK. F-Stack supports standard Nginx as HTTP framework which means all web application based on HTTP can easily use F-Stack.
4
5## How does Nginx use F-Stack?
6
7  Nginx APP is in `app/nginx-1.11.10` directory.
8
9```
10
11                                                    +--------+
12                                                    |
13+------------------------+                          |
14   channel: socketpair                              |  signal(reload, quit..)
15+------------------------+                          |
16                                                    |
17                                          +---------v--------+
18                                          |                  |
19                         +----------------+  master process  +---------------+
20                         |                |                  |               |
21                         |  channel       +----------+-------+               |
22                         |                           |              channel  |
23                         |                  channel  |                       |
24                         |                           |                       |
25               +---------+----------+     +----------+--------+    +---------+--------+
26               |                    |     |                   |    |                  |
27               | ff primary process |     |  worker process   |    |  worker process  |
28               |                    |     |                   |    |                  |
29               +--------------------+     +-------------------+    +------------------+
30                ff_init(primary)          +--------+  +-------+
31                loop:                     |        |  |       |
32                 handle channel event     | fstack |  |channel|
33                                          |  main  |  | event |
34                                          |  loop  |  |thread |
35                                          | thread |  |       |
36                                          |        |  |       |
37                                          +--------+  +-------+
38                                           woker       loop:
39                                          process      handle
40                                           cycle      channel
41                                                       event
42
43```
44
45- spawn an extra process ff primary: ff_init(primary);loop(handle channel event).This process doesn't handle SIGQUIT.
46
47- worker process has 2 threads. main thread: ff_init(secondary);ff_run(worker_process_cycle), channel thread: loop(handle channel event).
48
49Note that:
50- kni couldn't be enabled in this version, because kni is only processed by primary and worker `ff_primary` won't execute `ff_run()`.
51
52- supported nginx signals: reload(HUP)/reopen(USR1)/stop(TERM).
53
54- unsupported nginx signals: NGX_CHANGEBIN_SIGNAL(USR2).
55
56- when use `nginx -s reload`, you should make sure that `woker_processes` in nginx.conf and f-stack.conf haven't be modified.
57
58- necessary modifies in nginx.conf:
59
60```
61    user  root; # root account is necessary.
62    fstack_conf f-stack.conf;  # path of f-stack configuration file, default: $NGX_PREFIX/conf/f-stack.conf.
63    worker_processes  1; # should be equal to the lcore count of `dpdk.lcore_mask` in f-stack.conf.
64
65    events {
66        worker_connections  102400; # increase
67        use kqueue; # use kqueue
68    }
69
70    sendfile off; # sendfile off
71```
72
73## Nginx compiling
74	./configure --prefix=/usr/local/nginx_fstack --with-ff_module
75	make
76	make install
77
78