usr/src/lib/libilb/common/libilb.h

   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 */