xref: /illumos-gate/usr/src/lib/libilb/common/libilb.h (revision dbed73cb)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License (the "License").
6  * You may not use this file except in compliance with the License.
7  *
8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9  * or http://www.opensolaris.org/os/licensing.
10  * See the License for the specific language governing permissions
11  * and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL HEADER in each
14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15  * If applicable, add the following below this CDDL HEADER, with the
16  * fields enclosed by brackets "[]" replaced with your own identifying
17  * information: Portions Copyright [yyyy] [name of copyright owner]
18  *
19  * CDDL HEADER END
20  */
21 
22 /*
23  * Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
24  * Use is subject to license terms.
25  */
26 
27 #ifndef	_LIBILB_H
28 #define	_LIBILB_H
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33 
34 #include <sys/types.h>
35 #include <netinet/in.h>
36 #include <net/if.h>
37 
38 /* make sure these values stay in sync with definitions in ilb.h! */
39 #define	ILB_FLAGS_RULE_ENABLED	0x01
40 #define	ILB_FLAGS_RULE_STICKY	0x02
41 #define	ILB_FLAGS_RULE_ALLRULES	0x04
42 #define	ILB_FLAGS_RESERVED	0x08	/* in use by kernel, don't overlay */
43 
44 /*
45  * information whether we're interested in names or numerical information
46  */
47 #define	ILB_FLAGS_SRV_HOSTNAME	0x01	/* a servers hostname was given */
48 #define	ILB_FLAGS_SRV_PORTNAME	0x02	/* a port was spec'd by name */
49 
50 /*
51  * server status information
52  */
53 #define	ILB_FLAGS_SRV_ENABLED	0x10
54 
55 /*
56  * macros to determine, and for some cases, set status of server
57  */
58 #define	ILB_IS_SRV_ENABLED(f)		\
59 	((f & ILB_FLAGS_SRV_ENABLED) == ILB_FLAGS_SRV_ENABLED)
60 #define	ILB_IS_SRV_DISABLED(f)	((f & ILB_FLAGS_SRV_ENABLED) == 0)
61 
62 #define	ILB_SET_ENABLED(f)	(f |= ILB_FLAGS_SRV_ENABLED)
63 #define	ILB_SET_DISABLED(f)	(f &= ~ILB_FLAGS_SRV_ENABLED)
64 
65 #define	MAX_IP_SPREAD	0xff	/* largest ip addr. range */
66 
67 #define	ILB_HC_STR_UDP	"udp"
68 #define	ILB_HC_STR_TCP	"tcp"
69 #define	ILB_HC_STR_PING	"ping"
70 
71 #define	ILB_NAMESZ	20	/* keep in sync with kernel definition */
72 #define	ILB_SGNAME_SZ	(ILB_NAMESZ - 5) /* 3 numeric digits, "." and "_" */
73 
74 #define	ILB_SRVID_PREFIX  '_'	/* a valid serverID starts with this */
75 
76 /* producers of these statuses are libilb and ilbd functions */
77 typedef enum {
78 	ILB_STATUS_OK = 0,
79 	ILB_STATUS_INTERNAL,	/* an error internal to the library */
80 	ILB_STATUS_EINVAL,	/* invalid argument(s) */
81 	ILB_STATUS_ENOMEM,	/* not enough memory for operation */
82 	ILB_STATUS_ENOENT,	/* no such/no more element(s) */
83 	ILB_STATUS_SOCKET,	/* socket related failure */
84 	ILB_STATUS_READ,	/* read related failure */
85 	ILB_STATUS_WRITE,	/* write related failure */
86 	ILB_STATUS_TIMER,	/* healthcheck timer error */
87 	ILB_STATUS_INUSE,	/* item in use, cannot delete */
88 	ILB_STATUS_EEXIST,	/* scf item exist */
89 	ILB_STATUS_PERMIT,	/* no scf permit */
90 	ILB_STATUS_CALLBACK,	/* scf callback error */
91 	ILB_STATUS_EWOULDBLOCK,	/* operation is blocked - no error string */
92 	ILB_STATUS_INPROGRESS,	/* operation already in progress */
93 	ILB_STATUS_SEND,	/* send related failure */
94 	ILB_STATUS_GENERIC,	/* generic failure  - no error string */
95 	ILB_STATUS_ENOHCINFO,   /* missing healthcheck info */
96 	ILB_STATUS_INVAL_HCTESTTYPE,	/* invalid  health check */
97 	ILB_STATUS_INVAL_CMD, 	/* unknown command */
98 	ILB_STATUS_DUP_RULE,	/* rule name exists */
99 	ILB_STATUS_ENORULE,	/* rule does not exist */
100 	ILB_STATUS_MISMATCHSG,	/* addr family mismatch with sgroup */
101 	ILB_STATUS_MISMATCHH,	/* addr family mismatch with hosts/rule */
102 	ILB_STATUS_SGUNAVAIL,	/* cannot find sgroup in sggroup list */
103 	ILB_STATUS_SGINUSE,	/* server is un use, cannot remove */
104 	ILB_STATUS_SGEXISTS,	/* server exists */
105 	ILB_STATUS_SGFULL,   	/* cannot add any more servers */
106 	ILB_STATUS_SGEMPTY,  	/* sgroup is empty */
107 	ILB_STATUS_NAMETOOLONG,	/* a name is longer than allowed */
108 	ILB_STATUS_CFGAUTH,	/* config authoriz denied -no error string */
109 	ILB_STATUS_CFGUPDATE,	/* failed to update config! */
110 	ILB_STATUS_BADSG,	/* rules port range size does not match */
111 				/* that of the servers  */
112 	ILB_STATUS_INVAL_SRVR,   /* server port is incompatible with */
113 				/* rule port */
114 	ILB_STATUS_INVAL_ENBSRVR,   /* server  cannot be enabled since it's */
115 				    /* not being used by a rule */
116 	ILB_STATUS_BADPORT,	/* rules port value does not match */
117 				/* server's */
118 	ILB_STATUS_SRVUNAVAIL,	/* cannot find specified server */
119 	ILB_STATUS_RULE_NO_HC,	/* rule does not have hc info */
120 	ILB_STATUS_RULE_HC_MISMATCH,	/* rule and hc object mismatch */
121 	ILB_STATUS_HANDLE_CLOSING	/* library handle is being closed */
122 } ilb_status_t;
123 
124 typedef struct {
125 	int32_t		ia_af;		/* AF_INET or AF_INET6 */
126 	union {
127 		struct in_addr	v4;	/* network byte order */
128 		struct in6_addr	v6;	/* network byte order */
129 	} _au;
130 #define	ia_v4	_au.v4
131 #define	ia_v6	_au.v6
132 } ilb_ip_addr_t;
133 
134 /* Supported load balancing algorithm type */
135 typedef enum {
136 	ILB_ALG_ROUNDROBIN = 1,
137 	ILB_ALG_HASH_IP,
138 	ILB_ALG_HASH_IP_SPORT,
139 	ILB_ALG_HASH_IP_VIP
140 } ilb_algo_t;
141 
142 /* Supported load balancing method */
143 typedef enum {
144 	ILB_TOPO_DSR = 1,
145 	ILB_TOPO_NAT,
146 	ILB_TOPO_HALF_NAT
147 } ilb_topo_t;
148 
149 #define	ILB_INVALID_HANDLE ((void *) NULL)
150 
151 /*
152  * note: pointer to a non-existant struct
153  */
154 typedef struct ilb_handle *ilb_handle_t;
155 
156 /*
157  * Health check related information
158  */
159 
160 /* HC state of a server */
161 typedef enum {
162 	ILB_HCS_UNINIT = -1,	/* Uninitialized */
163 	ILB_HCS_UNREACH = 0,	/* Unreachable, ping fails */
164 	ILB_HCS_ALIVE,		/* Probe succeeds */
165 	ILB_HCS_DEAD,		/* Probe fails */
166 	ILB_HCS_DISABLED	/* Server is disabled */
167 } ilb_hc_srv_status_t;
168 
169 /*
170  * Struct representing a server in a hc object
171  *
172  * hcs_rule_name: rule using this server
173  * hcs_ID: server ID
174  * hcs_hc_name: hc object this server is associated with
175  * hcs_IP: IP address of the server
176  * hcs_fail_cnt: number of fail hc probe
177  * hcs_status: hc status of the server
178  * hcs_rtt: (in microsec) smoothed average RTT to the server
179  * hcs_lasttime: last time hc test was done (as returned by time(2))
180  * hcs_nexttime: next time hc test will be done (as returned by (time(2))
181  */
182 typedef struct {
183 	char		hcs_rule_name[ILB_NAMESZ];
184 	char		hcs_ID[ILB_NAMESZ];
185 	char		hcs_hc_name[ILB_NAMESZ];
186 	struct in6_addr hcs_IP;
187 	uint32_t	hcs_fail_cnt;
188 	ilb_hc_srv_status_t	hcs_status;
189 	uint32_t	hcs_rtt;
190 	time_t		hcs_lasttime;
191 	time_t		hcs_nexttime;
192 } ilb_hc_srv_t;
193 
194 /* Probe flags to be used in r_hcpflag in struct rule data. */
195 typedef enum {
196 	ILB_HCI_PROBE_ANY = 0,	/* Probe any port in the server port range */
197 	ILB_HCI_PROBE_FIX	/* Probe a fixed port */
198 } ilb_hcp_flags_t;
199 
200 /*
201  * Struct representing a hc object
202  *
203  * hci_name: name of the hc object
204  * hci_test: hc test to be done, TCP, UDP, or user supplied path name
205  * hci_timeout: (in sec) test time out
206  * hci_interval: (in sec) test execution interval
207  * hci_def_ping: true if default ping is done; false otherwise
208  */
209 typedef struct {
210 	char		hci_name[ILB_NAMESZ];
211 	char		hci_test[MAXPATHLEN];
212 	int32_t		hci_timeout;
213 	int32_t		hci_count;
214 	int32_t		hci_interval;
215 	boolean_t	hci_def_ping;
216 } ilb_hc_info_t;
217 
218 typedef struct rule_data {
219 	char		r_name[ILB_NAMESZ]; 	/* name of this rule */
220 	int32_t		r_flags;	/* opt: ILB_FLAGS_RULE_ENABLED etc. */
221 	ilb_ip_addr_t	r_vip;		/* vip, required for rule creation */
222 	uint16_t	r_proto;	/* protocol (tcp, udp) */
223 	in_port_t	r_minport;	/* port this rule refers to */
224 	in_port_t	r_maxport;	/* if != 0, defines port range */
225 	ilb_algo_t	r_algo;		/* round-robin, hash-ip, etc. */
226 	ilb_topo_t	r_topo;		/* dsr, NAT, etc */
227 	ilb_ip_addr_t	r_nat_src_start; /* required for NAT */
228 	ilb_ip_addr_t	r_nat_src_end;	/* required for NAT */
229 	ilb_ip_addr_t	r_stickymask;	/* netmask for persistence */
230 	uint32_t	r_conndrain;	/* opt: time for conn. draining (s) */
231 	uint32_t	r_nat_timeout;	/* opt: timeout for nat connections */
232 	uint32_t	r_sticky_timeout; /* opt: timeout for persistence */
233 	ilb_hcp_flags_t	r_hcpflag;	/* HC port flag */
234 	in_port_t	r_hcport;	/* opt with HC */
235 	char		r_sgname[ILB_SGNAME_SZ]; /* this rule's server grp. */
236 	char		r_hcname[ILB_NAMESZ];	/* HC name: optional */
237 } ilb_rule_data_t;
238 
239 /* not all fields are valid in all calls where this is used */
240 typedef struct server_data {
241 	ilb_ip_addr_t	sd_addr;	/* a server's ip address */
242 	in_port_t	sd_minport;	/* port information */
243 	in_port_t	sd_maxport;	/* ... if != 0, defines a port range */
244 	uint32_t	sd_flags;	/* enabled, dis- */
245 	char 		sd_srvID[ILB_NAMESZ];	/* "name" for server */
246 					/* assigned by system, not user */
247 } ilb_server_data_t;
248 
249 /*
250  * Struct to represent a server group.
251  *
252  * sgd_name: server group name
253  * sgd_flags: flags
254  * sgd_srvcount: number of servers in the group (not used in sever group
255  *               creation); filled in when used by call back function for
256  *               ilb_walk_servergroups().
257  */
258 typedef struct sg_data {
259 	char		sgd_name[ILB_SGNAME_SZ];
260 	int32_t		sgd_flags;
261 	int32_t		sgd_srvcount;
262 } ilb_sg_data_t;
263 
264 /*
265  * Struct to represent a NAT entry in kernel.
266  *
267  * nat_proto: transport protocol used in this NAT entry
268  *
269  * nat_out_global: IP address of client's request
270  * nat_out_global_port: port number of client's request
271  * nat_in_global: VIP of a rule for the NAT entry
272  * nat_in_global_port: port of a rule for the NAT entry
273  *
274  * nat_out_local: half NAT: IP address of client's request
275  *                full NAT: NAT'ed IP addres of client' request
276  * nat_out_local_port: half NAT: port number of client's request
277  *                     full NAT: NAT'ed port number of client's request
278  * nat_in_local: IP address of back end server handling this request
279  * nat_in_local_port: port number in back end server handling thi request
280  *
281  * (*) IPv4 address is represented as IPv4 mapped IPv6 address.
282  */
283 typedef struct {
284 	uint32_t	nat_proto;
285 
286 	in6_addr_t	nat_in_local;
287 	in6_addr_t	nat_in_global;
288 	in6_addr_t	nat_out_local;
289 	in6_addr_t	nat_out_global;
290 
291 	in_port_t	nat_in_local_port;
292 	in_port_t	nat_in_global_port;
293 	in_port_t	nat_out_local_port;
294 	in_port_t	nat_out_global_port;
295 } ilb_nat_info_t;
296 
297 /*
298  * Struct to represet a persistent entry in kernel.
299  *
300  * rule_name: the name of rule for a persistent entry
301  * req_addr: the client's IP address (*)
302  * srv_addr: the server's IP address (*) handling the client's request
303  *
304  * (*) IPv4 address is represented as IPv4 mapped IPv6 address.
305  */
306 typedef struct {
307 	char		persist_rule_name[ILB_NAMESZ];
308 	in6_addr_t	persist_req_addr;
309 	in6_addr_t	persist_srv_addr;
310 } ilb_persist_info_t;
311 
312 /*
313  * Function prototype of the call back function of those walker functions.
314  *
315  * Note: the storage of the data item parameter (ilb_sg_data_t/
316  * ilb_server_data_/ilb_rule_data_t/ilb_hc_info_t/ilb_hc_srv_t) will be
317  * freed after calling the call back function.  If the call back function
318  * needs to keep a copy of the data, it must copy the data content.
319  */
320 typedef ilb_status_t	(* sg_walkerfunc_t)(ilb_handle_t, ilb_sg_data_t *,
321     void *);
322 typedef ilb_status_t	(* srv_walkerfunc_t)(ilb_handle_t, ilb_server_data_t *,
323     const char *, void *);
324 typedef ilb_status_t	(* rule_walkerfunc_t)(ilb_handle_t, ilb_rule_data_t *,
325     void *);
326 typedef ilb_status_t	(* hc_walkerfunc_t)(ilb_handle_t, ilb_hc_info_t *,
327     void *);
328 typedef ilb_status_t	(* hc_srvwalkerfunc_t)(ilb_handle_t, ilb_hc_srv_t *,
329     void *);
330 
331 /*
332  * ilb_open creates a session handle that every caller into
333  * libilb needs to use
334  */
335 ilb_status_t	ilb_open(ilb_handle_t *);
336 
337 /*
338  * relinquish the session handle
339  */
340 ilb_status_t	ilb_close(ilb_handle_t);
341 
342 /* support and general functions */
343 ilb_status_t	ilb_reset_config(ilb_handle_t);
344 const char	*ilb_errstr(ilb_status_t);
345 
346 /* rule-related functions */
347 ilb_status_t	ilb_create_rule(ilb_handle_t, const ilb_rule_data_t *);
348 ilb_status_t	ilb_destroy_rule(ilb_handle_t, const char *);
349 ilb_status_t	ilb_disable_rule(ilb_handle_t, const char *);
350 ilb_status_t	ilb_enable_rule(ilb_handle_t, const char *);
351 ilb_status_t	ilb_walk_rules(ilb_handle_t, rule_walkerfunc_t, const char *,
352     void *);
353 
354 /* servergroup functionality */
355 ilb_status_t	ilb_create_servergroup(ilb_handle_t, const char *);
356 ilb_status_t	ilb_destroy_servergroup(ilb_handle_t, const char *);
357 ilb_status_t	ilb_add_server_to_group(ilb_handle_t, const char *,
358     ilb_server_data_t *);
359 ilb_status_t	ilb_rem_server_from_group(ilb_handle_t, const char *,
360     ilb_server_data_t *);
361 ilb_status_t	ilb_walk_servergroups(ilb_handle_t, sg_walkerfunc_t,
362     const char *, void *);
363 ilb_status_t	ilb_walk_servers(ilb_handle_t, srv_walkerfunc_t,
364     const char *, void *);
365 
366 /* functions for individual servers */
367 ilb_status_t	ilb_enable_server(ilb_handle_t, ilb_server_data_t *, void *);
368 ilb_status_t	ilb_disable_server(ilb_handle_t, ilb_server_data_t *, void *);
369 ilb_status_t	ilb_srvID_to_address(ilb_handle_t, ilb_server_data_t *,
370     const char *);
371 ilb_status_t	ilb_address_to_srvID(ilb_handle_t, ilb_server_data_t *,
372     const char *);
373 
374 /* health check-related functions */
375 ilb_status_t	ilb_create_hc(ilb_handle_t, const ilb_hc_info_t *);
376 ilb_status_t	ilb_destroy_hc(ilb_handle_t, const char *);
377 ilb_status_t	ilb_get_hc_info(ilb_handle_t, const char *, ilb_hc_info_t *);
378 ilb_status_t	ilb_walk_hc(ilb_handle_t, hc_walkerfunc_t, void *);
379 ilb_status_t	ilb_walk_hc_srvs(ilb_handle_t, hc_srvwalkerfunc_t,
380     const char *, void *);
381 
382 /* To show NAT table entries of ILB */
383 ilb_status_t	ilb_show_nat(ilb_handle_t, ilb_nat_info_t[], size_t *,
384     boolean_t *);
385 
386 /* To show persistent table entries of ILB */
387 ilb_status_t	ilb_show_persist(ilb_handle_t, ilb_persist_info_t[], size_t *,
388     boolean_t *);
389 
390 /* PRIVATE */
391 int ilb_cmp_ipaddr(ilb_ip_addr_t *, ilb_ip_addr_t *, int64_t *);
392 int ilb_cmp_in6_addr(struct in6_addr *, struct in6_addr *, int64_t *);
393 
394 #ifdef __cplusplus
395 }
396 #endif
397 
398 #endif /* _LIBILB_H */
399