1d203e6317e0a6d69470d74811a824996940e924
[idra/samba.git] / source3 / lib / server_prefork.h
1 /*
2    Unix SMB/CIFS implementation.
3    Common server globals
4
5    Copyright (C) Simo Sorce <idra@samba.org> 2011
6
7    This program is free software; you can redistribute it and/or modify
8    it under the terms of the GNU General Public License as published by
9    the Free Software Foundation; either version 3 of the License, or
10    (at your option) any later version.
11
12    This program is distributed in the hope that it will be useful,
13    but WITHOUT ANY WARRANTY; without even the implied warranty of
14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15    GNU General Public License for more details.
16
17    You should have received a copy of the GNU General Public License
18    along with this program.  If not, see <http://www.gnu.org/licenses/>.
19 */
20
21 #include "system/network.h"
22 #include <tevent.h>
23 #include "lib/tsocket/tsocket.h"
24
25 struct prefork_pool;
26
27 enum pf_worker_status {
28         PF_WORKER_NONE = 0,
29         PF_WORKER_ALIVE,
30         PF_WORKER_ACCEPTING,
31         PF_WORKER_EXITING
32 };
33
34 enum pf_server_cmds {
35         PF_SRV_MSG_NONE = 0,
36         PF_SRV_MSG_EXIT
37 };
38
39 /**
40 * @brief This structure is shared between the controlling parent and the
41 *        the child. The parent can only write to the 'cmds' and
42 *        'allowed_clients' variables, while a child is running.
43 *        The child can change 'status', and 'num_clients'.
44 *        All other variables are initialized by the parent before forking the
45 *        child.
46 */
47 struct pf_worker_data {
48         pid_t pid;
49         enum pf_worker_status status;
50         time_t started;
51         time_t last_used;
52         int num_clients;
53
54         enum pf_server_cmds cmds;
55         int allowed_clients;
56 };
57
58 /**
59 * @brief This is the 'main' function called by a child right after the fork.
60 *        It is daemon specific and should initialize and perform whatever
61 *        operation the child is meant to do. Returning from this function will
62 *        cause the termination of the child.
63 *
64 * @param ev             The event context
65 * @param msg_ctx        The messaging context
66 * @param pf             The mmaped area used to communicate with parent
67 * @param listen_fd_size The number of file descriptors to monitor
68 * @param listen_fds     The array of file descriptors
69 * @param private_data   Private data that needs to be passed to the main
70 *                       function from the calling parent.
71 *
72 * @return Returns the exit status to be reported to the parent via exit()
73 */
74 typedef int (prefork_main_fn_t)(struct tevent_context *ev,
75                                 struct messaging_context *msg_ctx,
76                                 struct pf_worker_data *pf,
77                                 int child_id,
78                                 int listen_fd_size,
79                                 int *listen_fds,
80                                 void *private_data);
81
82 /**
83 * @brief Callback function for parents that also want to be called on sigchld
84 *
85 * @param ev_ctx         The event context
86 * @param pool           The pool handler
87 * @param private_data   Data private to the parent
88 */
89 typedef void (prefork_sigchld_fn_t)(struct tevent_context *ev_ctx,
90                                     struct prefork_pool *pool,
91                                     void *private_data);
92
93 /* ==== Functions used by controlling process ==== */
94
95 /**
96 * @brief Creates the first pool of preforked processes
97 *
98 * @param mem_ctx        The memory context used to hold the pool structure
99 * @param ev_ctx         The event context
100 * @param msg_ctx        The messaging context
101 * @param listen_fd_size The number of file descriptors to monitor
102 * @param listen_fds     The array of file descriptors to monitor
103 * @param min_children   Minimum number of children that must be available at
104 *                       any given time
105 * @param max_children   Maximum number of children that can be started. Also
106 *                       determines the initial size of the pool.
107 * @param main_fn        The children 'main' function to be called after fork
108 * @param private_data   The children private data.
109 * @param pf_pool        The allocated pool.
110 *
111 * @return True if it was successful, False otherwise.
112 */
113 bool prefork_create_pool(TALLOC_CTX *mem_ctx,
114                          struct tevent_context *ev_ctx,
115                          struct messaging_context *msg_ctx,
116                          int listen_fd_size, int *listen_fds,
117                          int min_children, int max_children,
118                          prefork_main_fn_t *main_fn, void *private_data,
119                          struct prefork_pool **pf_pool);
120 /**
121 * @brief Function used to attempt to expand the size of children.
122 *
123 * @param pfp            The pool structure.
124 * @param new_max        The new max number of children.
125 *
126 * @return 0 if operation was successful
127 *         ENOSPC if the mmap area could not be grown to the requested size
128 *         EINVAL if the new max is invalid.
129 *
130 * NOTE: this function can easily fail if the mmap area cannot be enlarged.
131 *       A well behaving parent MUST NOT error out if this happen.
132 */
133 int prefork_expand_pool(struct prefork_pool *pfp, int new_max);
134
135 /**
136 * @brief Used to prefork a number of new children
137 *
138 * @param ev_ctx         The event context
139 * @param msg_ctx        The messaging context
140 * @param pfp            The pool structure
141 * @param num_children   The number of children to be started
142 *
143 * @return The number of new children effectively forked.
144 *
145 * NOTE: This method does not expand the pool, if the max number of children
146 *       has already been forked it will do nothing.
147 */
148 int prefork_add_children(struct tevent_context *ev_ctx,
149                          struct messaging_context *msg_ctx,
150                          struct prefork_pool *pfp,
151                          int num_children);
152 /**
153 * @brief Commands a number of children to stop and exit
154 *
155 * @param msg_ctx        The messaging context.
156 * @param pfp            The pool.
157 * @param num_children   The number of children we need to retire.
158 * @param age_limit      The minimum age a child has been active to be
159 *                       considered for retirement. (Compared against the
160 *                       'started' value in the pf_worker_data structure of the
161 *                       children.
162 *
163 * @return Number of children that were signaled to stop
164 *
165 * NOTE: Only children that have no attached clients can be stopped.
166 *       If all the available children are too young or are busy then it
167 *       is possible that none will be asked to stop.
168 */
169 int prefork_retire_children(struct messaging_context *msg_ctx,
170                             struct prefork_pool *pfp,
171                             int num_children, time_t age_limit);
172 /**
173 * @brief Count the number of children
174 *
175 * @param pfp    The pool.
176 * @param active Number of children currently active if not NULL
177 *
178 * @return The total number of children.
179 */
180 int prefork_count_children(struct prefork_pool *pfp, int *active);
181
182 /**
183 * @brief Count the number of actual connections currently allowed
184 *
185 * @param pfp            The pool.
186 *
187 * @return The number of connections that can still be opened by clients
188 *         with the current pool of children.
189 */
190 int prefork_count_allowed_connections(struct prefork_pool *pfp);
191
192 /**
193 * @brief Increase the amount of clients each child is allowed to handle
194 *        simultaneaously. It will allow each child to handle more than
195 *        one client at a time, up to 'max' (currently set to 100).
196 *
197 * @param pfp    The pool.
198 * @param max    Max number of allowed connections per child
199 */
200 void prefork_increase_allowed_clients(struct prefork_pool *pfp, int max);
201
202 /**
203 * @brief Decrease the amount of clients each child is allowed to handle.
204 *        Min is 1.
205 *
206 * @param pfp    The pool.
207 */
208 void prefork_decrease_allowed_clients(struct prefork_pool *pfp);
209
210 /**
211 * @brief Reset the maximum allowd clients per child to 1.
212 *        Does not reduce the number of clients actually beeing served by
213 *        any given child, but prevents children from overcommitting from
214 *        now on.
215 *
216 * @param pfp    The pool.
217 */
218 void prefork_reset_allowed_clients(struct prefork_pool *pfp);
219
220 /**
221 * @brief Send a specific signal to all children.
222 *        Used to send SIGHUP when a reload of the configuration is needed
223 *        for example.
224 *
225 * @param pfp            The pool.
226 * @param signal_num     The signal number to be sent.
227 */
228 void prefork_send_signal_to_all(struct prefork_pool *pfp, int signal_num);
229
230 /**
231 * @brief Send a message to all children that the server changed something
232 *        in the pool and they may want to take action.
233 *
234 * @param msg_ctx        The messaging context.
235 * @param pfp            The pool.
236 */
237 void prefork_warn_active_children(struct messaging_context *msg_ctx,
238                                   struct prefork_pool *pfp);
239
240 /**
241 * @brief Sets the SIGCHLD callback
242 *
243 * @param pfp            The pool handler.
244 * @param sigchld_fn     The callback function (pass NULL to unset).
245 * @param private_data   Private data for the callback function.
246 */
247 void prefork_set_sigchld_callback(struct prefork_pool *pfp,
248                                   prefork_sigchld_fn_t *sigchld_fn,
249                                   void *private_data);
250
251 /* ==== Functions used by children ==== */
252
253 /**
254 * @brief Try to listen and accept on one of the listening sockets.
255 *        Asynchronusly tries to grab the lock and perform an accept.
256 *        Will automatically update the 'status' of the child and handle
257 *        all the locking/unlocking/timingout as necessary.
258 *        Changes behavior depending on whether the child already has other
259 *        client connections. If not it blocks on the lock call for periods of
260 *        time. Otherwise it loops on the lock using a timer in order to allow
261 *        processing of the other clients requests.
262 *
263 * @param mem_ctx        The memory context on whic to allocate the request
264 * @param ev             The event context
265 * @param pf             The child/parent shared structure
266 * @param listen_fd_size The number of listening file descriptors
267 * @param listen_fds     The array of listening file descriptors
268 *
269 * @return The tevent request pointer or NULL on allocation errors.
270 */
271 struct tevent_req *prefork_listen_send(TALLOC_CTX *mem_ctx,
272                                         struct tevent_context *ev,
273                                         struct pf_worker_data *pf,
274                                         int listen_fd_size,
275                                         int *listen_fds);
276 /**
277 * @brief Returns the file descriptor after the new client connection has
278 *        been accepted.
279 *
280 * @param req            The request
281 * @param mem_ctx        The memory context for cli_addr and srv_addr
282 * @param fd             The new file descriptor.
283 * @param srv_addr       The server address in tsocket_address format
284 * @param cli_addr       The client address in tsocket_address format
285 *
286 * @return       The error in case the operation failed.
287 */
288 int prefork_listen_recv(struct tevent_req *req,
289                         TALLOC_CTX *mem_ctx, int *fd,
290                         struct tsocket_address **srv_addr,
291                         struct tsocket_address **cli_addr);
292