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