xref: /f-stack/doc/F-Stack_Nginx_APP_Guide.md (revision 144c6bcd) 
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### New nginx module `ngx_ff_module.c`
10
11Hook operation of Network IO interface , the transformation of the ff socket, in order to distinguish from regular file descriptor.
12
13First, define network interface functions.
14
15    static int (*real_close)(int);
16    static int (*real_socket)(int, int, int);
17    static int (*real_bind)(int, const struct sockaddr*, socklen_t);
18    static int (*real_connect)(int, const struct sockaddr*, socklen_t);
19    static int (*real_listen)(int, int);
20    static int (*real_setsockopt)(int, int, int, const void *, socklen_t);
21
22    static int (*real_accept)(int, struct sockaddr *, socklen_t *);
23    static int (*real_accept4)(int, struct sockaddr *, socklen_t *, int);
24    static ssize_t (*real_recv)(int, void *, size_t, int);
25    static ssize_t (*real_send)(int, const void *, size_t, int);
26
27    static ssize_t (*real_writev)(int, const struct iovec *, int);
28    static ssize_t (*real_write)(int, const void *, size_t );
29    static ssize_t (*real_read)(int, void *, size_t );
30    static ssize_t (*real_readv)(int, const struct iovec *, int);
31
32    static int (*real_ioctl)(int, int, void *);
33
34    static int (*real_select) (int, fd_set *, fd_set *, fd_set *, struct timeval *);
35
36Initialize the F-Stack module, hook network interface functions, using our interface to replace the System Interface. Initialize F-Stack.
37
38      void ff_mod_init(int argc, char * const *argv) {
39        int rc;
40
41        #define INIT_FUNCTION(func) \
42            real_##func = dlsym(RTLD_NEXT, #func); \
43            assert(real_##func)
44
45        INIT_FUNCTION(socket);
46        INIT_FUNCTION(bind);
47        INIT_FUNCTION(connect);
48        INIT_FUNCTION(close);
49        INIT_FUNCTION(listen);
50        INIT_FUNCTION(setsockopt);
51        INIT_FUNCTION(accept);
52        INIT_FUNCTION(accept4);
53        INIT_FUNCTION(recv);
54        INIT_FUNCTION(send);
55        INIT_FUNCTION(writev);
56        INIT_FUNCTION(write);
57        INIT_FUNCTION(read);
58        INIT_FUNCTION(readv);
59
60        INIT_FUNCTION(ioctl);
61        INIT_FUNCTION(select);
62
63    #undef INIT_FUNCTION
64
65        assert(argc >= 2);
66
67        rc = ff_init(argv[1], argc, argv);
68        assert(0 == rc);
69
70        inited = 1;
71    }
72
73Re-implement the network interface with FF API to replace the System network interface. Take socket () as an example, use ff\_socket instead of real\_socket, and return the F-Stack file descriptor. Other APIs refers to module code.
74
75    int socket(int domain, int type, int protocol)
76    {
77        int rc;
78
79        if ((inited == 0) ||  (AF_INET != domain) || (SOCK_STREAM != type && SOCK_DGRAM != type))
80        {
81            rc = real_socket(domain, type, protocol);
82            return rc;
83        }
84
85        rc = ff_socket(domain, type, protocol);
86        if(rc >= 0)
87            rc |= 1 << FST_FD_BITS;
88
89        return rc;
90    }
91
92### Other modifications
93
94 `auto/sources`
95
96Add compiling file
97
98 `auto/make`
99
100Add link lib
101
102 `auto/options`
103
104Add module
105
106`ngx_kqueue_module.c`
107
108kqueue module adapted to F-Stack ff API
109
110## Start Nginx compiling
111
112Configuration needs to include F-Stack `ff_module`
113
114	./configure --prefix=/usr/local/nginx_fstack --with-ff_module
115	make
116	make install
117
118Notes for Nginx based F-Stack configuration file.
119
120	worker_processes  1; # always be 1
121
122	events {
123		worker_connections  102400; # to 102400
124		use kqueue; # use kqueue
125	}
126
127	sendfile off; # sendfile off
128
129Start Nginx with `start.sh`
130
131    ./start.sh -b /usr/local/nginx_fstack/sbin/nginx -c config.ini
132
133 or with the method below. Description of arguments is as bellow,
134
135	#	-c coremask, The primary and secondary processes need to specify the coremask of the individual lcore they want to use, for example, primary process -c 1, secondary -c 2, -c 4, -c 8, -c 10, etc.
136	#	--proc-type = primary/secondary primary/secondary
137	#	--num-procs = number of process
138	#	--proc-id = current process ID, increase from 0
139
140	<nginx_dir>/nginx config.ini -c <cmask>  --proc-type=primary --num-procs=<num_procs> --proc-id=<proc_id> # primary process
141	<nginx_dir>/nginx config.ini -c <cmask>  --proc-type=secondary --num-procs=<num_procs> --proc-id=<proc_id> # seconary process, if needed
142
143 Other is identical to the standard Nginx.
144