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