xref: /f-stack/doc/F-Stack_Nginx_APP_Guide.md (revision bb4234c8) 
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                            channel: socketpair         |
14                         +------------------------+     |  signal(reload, quit..)
15                                                        |
16                                                        |
17                                              +---------v--------+
18                                              |                  |
19                             +----------------+  master process  +---------------+
20                             |                |                  |               |
21                             |  channel       +----------+-------+               |
22                             |                           |              channel  |
23                             |                  channel  |                       |
24                             |                           |                       |
25                   +---------+----------+     +----------+--------+    +---------+--------+
26first one to start |                    |     |                   |    |                  |
27 last one to exit<-+   primary worker   |     |  secondary worker |    | secondary worker |
28                   |                    |     |                   |    |                  |
29                   +--------------------+     +-------------------+    +------------------+
30                   +--------------------+     +-------------------+
31                   |                    |     |                   |
32                   |   fstack,kernel    |     |   fstack,kernel   |
33                   |     and channel    |     |     and channel   |
34                   |     loop thread    |     |     loop thread   |
35                   |                    |     |			  |
36                   +--------------------+     +-------------------+
37                    woker process cycle        woker process cycle
38
39```
40
41- spawn primary worker firstly, and then wait for primary startup, continue to spawn secondary workers.
42
43- a major addition to the worker process is fstack-handling：ff_init();ff_run(worker_process_cycle); worker_process_cycle(handle channel/host/fstack event).
44
45- a new directive `kernel_network_stack` :
46```
47    Syntax: kernel_network_stack on | off;
48    Default: kernel_network_stack off;
49    Context: http, server
50    This directive is available only when ```NGX_HAVE_FSTACK``` is defined.
51    Determines whether server should run on kernel network stack or fstack.
52```
53
54Note that:
55
56- the `reload` is not graceful, service will still be unavailable during the process of reloading.
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