1 /*
2 * include/proto/listener.h
3 * This file declares listener management primitives.
4 *
5 * Copyright (C) 2000-2012 Willy Tarreau - w@1wt.eu
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation, version 2.1
10 * exclusively.
11 *
12 * This library 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 GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, write to the Free Software
19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
20 */
21
22 #ifndef _PROTO_LISTENER_H
23 #define _PROTO_LISTENER_H
24
25 #include <string.h>
26
27 #include <types/listener.h>
28 #include <types/cli.h>
29
30 /* This function tries to temporarily disable a listener, depending on the OS
31 * capabilities. Linux unbinds the listen socket after a SHUT_RD, and ignores
32 * SHUT_WR. Solaris refuses either shutdown(). OpenBSD ignores SHUT_RD but
33 * closes upon SHUT_WR and refuses to rebind. So a common validation path
34 * involves SHUT_WR && listen && SHUT_RD. In case of success, the FD's polling
35 * is disabled. It normally returns non-zero, unless an error is reported.
36 */
37 int pause_listener(struct listener *l);
38
39 /* This function tries to resume a temporarily disabled listener.
40 * The resulting state will either be LI_READY or LI_FULL. 0 is returned
41 * in case of failure to resume (eg: dead socket).
42 */
43 int resume_listener(struct listener *l);
44
45 /* This function adds all of the protocol's listener's file descriptors to the
46 * polling lists when they are in the LI_LISTEN state. It is intended to be
47 * used as a protocol's generic enable_all() primitive, for use after the
48 * fork(). It puts the listeners into LI_READY or LI_FULL states depending on
49 * their number of connections. It always returns ERR_NONE.
50 */
51 int enable_all_listeners(struct protocol *proto);
52
53 /* This function removes all of the protocol's listener's file descriptors from
54 * the polling lists when they are in the LI_READY or LI_FULL states. It is
55 * intended to be used as a protocol's generic disable_all() primitive. It puts
56 * the listeners into LI_LISTEN, and always returns ERR_NONE.
57 */
58 int disable_all_listeners(struct protocol *proto);
59
60 /* Dequeues all of the listeners waiting for a resource in wait queue <queue>. */
61 void dequeue_all_listeners(struct list *list);
62
63 /* Must be called with the lock held. Depending on <do_close> value, it does
64 * what unbind_listener or unbind_listener_no_close should do.
65 */
66 void do_unbind_listener(struct listener *listener, int do_close);
67
68 /* This function closes the listening socket for the specified listener,
69 * provided that it's already in a listening state. The listener enters the
70 * LI_ASSIGNED state. This function is intended to be used as a generic
71 * function for standard protocols.
72 */
73 void unbind_listener(struct listener *listener);
74
75 /* This function pretends the listener is dead, but keeps the FD opened, so
76 * that we can provide it, for conf reloading.
77 */
78 void unbind_listener_no_close(struct listener *listener);
79
80 /* This function closes all listening sockets bound to the protocol <proto>,
81 * and the listeners end in LI_ASSIGNED state if they were higher. It does not
82 * detach them from the protocol. It always returns ERR_NONE.
83 */
84 int unbind_all_listeners(struct protocol *proto);
85
86
87 /* creates one or multiple listeners for bind_conf <bc> on sockaddr <ss> on port
88 * range <portl> to <porth>, and possibly attached to fd <fd> (or -1 for auto
89 * allocation). The address family is taken from ss->ss_family. The number of
90 * jobs and listeners is automatically increased by the number of listeners
91 * created. If the <inherited> argument is set to 1, it specifies that the FD
92 * was obtained from a parent process.
93 * It returns non-zero on success, zero on error with the error message
94 * set in <err>.
95 */
96 int create_listeners(struct bind_conf *bc, const struct sockaddr_storage *ss,
97 int portl, int porth, int fd, int inherited, char **err);
98
99 /* Delete a listener from its protocol's list of listeners. The listener's
100 * state is automatically updated from LI_ASSIGNED to LI_INIT. The protocol's
101 * number of listeners is updated. Note that the listener must have previously
102 * been unbound. This is the generic function to use to remove a listener.
103 */
104 void delete_listener(struct listener *listener);
105
106 /* This function is called on a read event from a listening socket, corresponding
107 * to an accept. It tries to accept as many connections as possible, and for each
108 * calls the listener's accept handler (generally the frontend's accept handler).
109 */
110 void listener_accept(int fd);
111
112 /* Notify the listener that a connection initiated from it was released. This
113 * is used to keep the connection count consistent and to possibly re-open
114 * listening when it was limited.
115 */
116 void listener_release(struct listener *l);
117
118 /*
119 * Registers the bind keyword list <kwl> as a list of valid keywords for next
120 * parsing sessions.
121 */
122 void bind_register_keywords(struct bind_kw_list *kwl);
123
124 /* Return a pointer to the bind keyword <kw>, or NULL if not found. */
125 struct bind_kw *bind_find_kw(const char *kw);
126
127 /* Dumps all registered "bind" keywords to the <out> string pointer. */
128 void bind_dump_kws(char **out);
129
130 /* allocate an bind_conf struct for a bind line, and chain it to the frontend <fe>.
131 * If <arg> is not NULL, it is duplicated into ->arg to store useful config
132 * information for error reporting.
133 */
bind_conf_alloc(struct proxy * fe,const char * file,int line,const char * arg,struct xprt_ops * xprt)134 static inline struct bind_conf *bind_conf_alloc(struct proxy *fe, const char *file,
135 int line, const char *arg, struct xprt_ops *xprt)
136 {
137 struct bind_conf *bind_conf = (void *)calloc(1, sizeof(struct bind_conf));
138
139 bind_conf->file = strdup(file);
140 bind_conf->line = line;
141 LIST_ADDQ(&fe->conf.bind, &bind_conf->by_fe);
142 if (arg)
143 bind_conf->arg = strdup(arg);
144
145 bind_conf->ux.uid = -1;
146 bind_conf->ux.gid = -1;
147 bind_conf->ux.mode = 0;
148 bind_conf->xprt = xprt;
149 bind_conf->frontend = fe;
150 bind_conf->severity_output = CLI_SEVERITY_NONE;
151
152 LIST_INIT(&bind_conf->listeners);
153 return bind_conf;
154 }
155
listener_state_str(const struct listener * l)156 static inline const char *listener_state_str(const struct listener *l)
157 {
158 static const char *states[9] = {
159 "NEW", "INI", "ASS", "PAU", "ZOM", "LIS", "RDY", "FUL", "LIM",
160 };
161 unsigned int st = l->state;
162
163 if (st >= sizeof(states) / sizeof(*states))
164 return "INVALID";
165 return states[st];
166 }
167
168 extern struct xfer_sock_list *xfer_sock_list;
169 #endif /* _PROTO_LISTENER_H */
170
171 /*
172 * Local variables:
173 * c-indent-level: 8
174 * c-basic-offset: 8
175 * End:
176 */
177