//+---------------------------------------------------------------------------- // // File: wlbsconfig.h // // Module: Network Load Balancing // // Description: Internal APIs for cluster configuration. Thes APIs are internal // to WLBS team only, and no plan backward compatability. // // Copyright (C) Microsoft Corporation. All rights reserved. // // Author: fengsun Created 3/2/00 // //+---------------------------------------------------------------------------- #ifndef _WLBSCONFIG_H #define _WLBSCONFIG_H #ifdef __cplusplus extern "C" { #endif #include "wlbsctrl.h" /* Maximum lengths of parameter strings. */ #define WLBS_MAX_VIRTUAL_NIC 256 #define WLBS_MAX_CLUSTER_NIC 256 #define WLBS_MAX_NETWORK_ADDR 17 #define WLBS_MAX_CL_IP_ADDR 17 #define WLBS_MAX_CL_NET_MASK 17 #define WLBS_MAX_DED_IP_ADDR 17 #define WLBS_MAX_DED_NET_MASK 17 #define WLBS_MAX_NETWORK_ADDR 17 #define WLBS_MAX_LICENSE_KEY 20 #define WLBS_MAX_DOMAIN_NAME 100 #define WLBS_MAX_BDA_TEAM_ID 40 /* Port group rule - used in registry parameters. NOTE! do not access value marked with I. These are for internal use only. */ #pragma pack(1) typedef struct { DWORD start_port, /* Starting port number. */ end_port; /* Ending port number. */ #ifdef WLBSAPI_INTERNAL_ONLY DWORD code; /* I: Unique rule code. */ #else DWORD Private1; // Do not change these field directly #endif DWORD mode; /* Filtering mode. */ DWORD protocol; /* WLBS_TCP, WLBS_UDP or WLBS_TCP_UDP */ #ifdef WLBSAPI_INTERNAL_ONLY DWORD valid; /* I: For rule management in user mode. */ #else DWORD Private2; // Do not change these field directly #endif union { struct { DWORD priority; /* Mastership priority: 1..32 or 0 for not-specified. */ } single; /* Data for single server mode. */ struct { WORD equal_load; /* TRUE - Even load distribution. */ WORD affinity; /* WLBS_AFFINITY_... */ DWORD load; /* Percentage of load to handle locally 0..100. */ } multi; /* Data for multi-server mode. */ } mode_data; /* Data for appropriate port group mode. */ } WLBS_OLD_PORT_RULE, * PWLBS_OLD_PORT_RULE; /* Structure to hold the bi-directional affinity registry settings. */ typedef struct _CVY_BDA { WCHAR team_id[WLBS_MAX_BDA_TEAM_ID + 1]; /* The team ID - MUST be a GUID. */ ULONG active; /* On write, this flag determines whether to create BDATeaming key - BDA on/off switch. */ ULONG master; /* Boolean indication of master status. */ ULONG reverse_hash; /* Sets direction of hashing - forward (normal) or reverse. */ } WLBS_BDA, PWLBS_BDA; typedef struct { TCHAR virtual_ip_addr [WLBS_MAX_CL_IP_ADDR + 1]; /* Virtual IP Address */ DWORD start_port, /* Starting port number. */ end_port; /* Ending port number. */ #ifdef WLBSAPI_INTERNAL_ONLY DWORD code; /* I: Unique rule code. */ #else DWORD Private1; // Do not change these field directly #endif DWORD mode; /* Filtering mode. */ DWORD protocol; /* WLBS_TCP, WLBS_UDP or WLBS_TCP_UDP */ #ifdef WLBSAPI_INTERNAL_ONLY DWORD valid; /* I: For rule management in user mode. */ #else DWORD Private2; // Do not change these field directly #endif union { struct { DWORD priority; /* Mastership priority: 1..32 or 0 for not-specified. */ } single; /* Data for single server mode. */ struct { WORD equal_load; /* TRUE - Even load distribution. */ WORD affinity; /* WLBS_AFFINITY_... */ DWORD load; /* Percentage of load to handle locally 0..100. */ } multi; /* Data for multi-server mode. */ } mode_data; /* Data for appropriate port group mode. */ } WLBS_PORT_RULE, * PWLBS_PORT_RULE; #pragma pack() #ifdef __cplusplus typedef struct __declspec(dllexport) #else typedef struct #endif { /* public - can be modified by clients of this API */ DWORD host_priority; /* Host priority ID. */ DWORD alive_period; /* Period for sending "I am alive" messages in milliseconds. */ DWORD alive_tolerance; /* How many "I am alive" messages can be missed from other servers before assuming that the host is dead. */ DWORD num_actions; /* Number of actions per allocation. */ DWORD num_packets; /* number of packets per allocation. */ DWORD num_send_msgs; /* Number of heartbeats per allocation. */ DWORD install_date; /* Install time stamp, used to create a unique code for the host. */ DWORD rct_port; /* Remote control UDP port. */ DWORD rct_enabled; /* TRUE - remote control enabled. */ DWORD cluster_mode; /* TRUE - join cluster on boot. */ DWORD dscr_per_alloc; /* Number of connection tracking descriptor per allocation. */ DWORD max_dscr_allocs; /* Maximum number of connection tracking descriptor allocations. */ DWORD mcast_support; /* TRUE - multicast mode, FALSE - unicast mode */ DWORD mask_src_mac; /* TRUE - Mangle source MAC address to prevent switch learning. FALSE - cluster is on a hub, optimizes switch performance by re-enabling learning. */ TCHAR cl_mac_addr [WLBS_MAX_NETWORK_ADDR + 1]; /* Cluster MAC address. */ TCHAR cl_ip_addr [WLBS_MAX_CL_IP_ADDR + 1]; /* Cluster IP address. */ TCHAR cl_net_mask [WLBS_MAX_CL_NET_MASK + 1]; /* Netmask for cluster IP. */ TCHAR ded_ip_addr [WLBS_MAX_DED_IP_ADDR + 1]; /* Dedicated IP address or "" for none. */ TCHAR ded_net_mask [WLBS_MAX_DED_NET_MASK + 1]; /* Netmask for dedicated IP address or "" for none */ TCHAR domain_name [WLBS_MAX_DOMAIN_NAME + 1]; /* FQDN of the cluster. */ // // IGMP support // BOOL fIGMPSupport; // whether to send IGMP join periodically WCHAR szMCastIpAddress[WLBS_MAX_CL_IP_ADDR + 1]; // multicast IP BOOL fIpToMCastIp; // whether to generate multicast IP from cluster IP WLBS_BDA bda_teaming; #ifdef __cplusplus #ifndef WLBSAPI_INTERNAL_ONLY // // private - should be treated as opaque // // Do not change these field directly // private: #endif #endif /* obtained from the registry */ DWORD i_parms_ver; /* I: Parameter structure version. */ DWORD i_verify_date; /* I: Encoded install time stamp. */ DWORD i_rmt_password; /* I: Remote maintenance password. */ DWORD i_rct_password; /* I: Remote control password (use WlbsSetRemotePassword to set this value). */ DWORD i_num_rules; /* I: # active port group rules (changed through WlbsAddPortRule and WlbsDelPortRule routines). */ DWORD i_cleanup_delay; /* I: Dirty connection cleanup delay in milliseconds, 0 - delay. */ DWORD i_scale_client; /* I: Legacy parameter. */ DWORD i_mcast_spoof; /* I: TRUE - Provide ARP resolution in multicast mode. FALSE - clients will rely on static ARP entries. */ DWORD i_convert_mac; /* I: TRUE - automatically generate MAC address based on cluster IP address in UI. */ DWORD i_ip_chg_delay; /* I: Delay in milliseconds to block outgoing ARPs while IP address change is in process. */ DWORD i_nbt_support; /* I: TRUE - NBT cluster name support enabled. */ DWORD i_netmon_alive; /* I: TRUE - pass heartbeat messages to the protocols (netmon). */ DWORD i_effective_version; /* I: Effective version of NLB */ /* strings */ TCHAR i_virtual_nic_name [WLBS_MAX_VIRTUAL_NIC + 1]; /* I: Virtual NIC name or GUID. */ // TCHAR cluster_nic_name [WLBS_MAX_CLUSTER_NIC + 1]; /* I: Cluster NIC name or GUID. */ TCHAR i_license_key [WLBS_MAX_LICENSE_KEY + 1]; /* I: Legacy parameter. */ WLBS_PORT_RULE i_port_rules [WLBS_MAX_RULES]; /* I: Port rules (changed through WlbsAddPortRule and WlbsDelPortRule routines). */ /* computed */ DWORD i_max_hosts; /* Legacy parameter. */ DWORD i_max_rules; /* Legacy parameter. */ // DWORD i_expiration; /* Legacy parameter. */ // DWORD i_ft_rules_enabled; /* Legacy parameter. */ // DWORD version; /* Legacy parameter. */ DWORD i_dwReserved; } WLBS_REG_PARAMS, * PWLBS_REG_PARAMS; /* API commands for WlbsFormatMessage */ typedef enum { CmdWlbsAddPortRule, CmdWlbsAddressToName, CmdWlbsAddressToString, CmdWlbsAdjust, CmdWlbsCommitChanges, CmdWlbsDeletePortRule, CmdWlbsDestinationSet, CmdWlbsDisable, CmdWlbsDrain, CmdWlbsDrainStop, CmdWlbsEnable, CmdWlbsFormatMessage, CmdWlbsGetEffectiveVersion, CmdWlbsGetNumPortRules, CmdWlbsEnumPortRules, CmdWlbsGetPortRule, CmdWlbsInit, CmdWlbsPasswordSet, CmdWlbsPortSet, CmdWlbsQuery, CmdWlbsReadReg, CmdWlbsResolve, CmdWlbsResume, CmdWlbsSetDefaults, CmdWlbsSetRemotePassword, CmdWlbsStart, CmdWlbsStop, CmdWlbsSuspend, CmdWlbsTimeoutSet, CmdWlbsWriteReg } WLBS_COMMAND; extern BOOL WINAPI WlbsFormatMessage ( DWORD error, /* IN - WLBS_... or WSA... return value. */ WLBS_COMMAND command, /* IN - Which routine returned the value. */ BOOL cluster, /* IN - TRUE - command was issued on entire cluster, FALSE - single host. */ WCHAR* messagep, /* IN - Pointer to user-allocated buffer. */ PDWORD lenp /* IN - Buffer size. OUT - The required buffer size if the current size is insufficient */ ); /* Return character string describing specified WLBS API return code. Note that message will depend on the command which returned the code and if it was issued in cluster-wide or single-host mode. returns: TRUE => Message formatted successfully. FALSE => Bad error code (lenp will contain 0 on exit) or buffer is not big enough to contain entire string (lenp will contain required buffer size on exit). */ /* Support routines: */ extern DWORD WINAPI WlbsResolve ( const WCHAR* address /* IN - Internet host name or IP address in dotted notation. */ ); /* Resolve Internet host name to its IP address. This routine can also be used to convert a string containing an IP address in dotted notation to a value that can be passed to cluster control routines. returns: 0 => failed to resolve host name.
=> IP address corresponding to the specified address. This value can be used in subsequent calls to cluster control routines. */ extern BOOL WINAPI WlbsAddressToString ( DWORD address, /* IN - IP address. */ WCHAR* buf, /* OUT - Character buffer for resulting string. */ PDWORD lenp /* IN - Buffer size in characters. OUT - Characters written or required buffer size. */ ); /* Convert IP address to a string in dotted notation. returns: TRUE => Successfully converted. lenp contains number of character written. FALSE => Buffer too small. lenp contains required buffer size including terminating NULL character. */ extern BOOL WINAPI WlbsAddressToName ( DWORD address, /* IN - IP address. */ WCHAR* buf, /* OUT - Character buffer for resulting string. */ PDWORD lenp /* IN - Buffer size in characters. OUT - Characters written or required buffer size. */ ); /* Resolve IP address to Internet host name. returns: TRUE => Successfully converted. lenp contains number of character written. FALSE => Buffer too small. lenp contains required buffer size including terminating NULL character. */ /****************************************************************************** Cluster host configuration routines. Note that in current implementation, cluster and host parameters need to be set to WLBS_LOCAL_CLUSTER and WLBS_LOCAL_HOST. ******************************************************************************/ extern DWORD WINAPI WlbsReadReg ( DWORD cluster, /* IN - WLBS_LOCAL_CLUSTER */ PWLBS_REG_PARAMS reg_data /* OUT - Registry parameters */ ); /* Read WLBS registry data. returns: WLBS_INIT_ERROR => Error initializing control module. Cannot perform control operations. WLBS_BAD_PARAMS => reg_data is NULL WLBS_REG_ERROR => Error reading from the registry Local: WLBS_OK => Registry parameters successfully read. Remote: WLBS_LOCAL_ONLY => This call is implemented for local only operation. */ extern DWORD WINAPI WlbsWriteReg ( DWORD cluster, /* IN - WLBS_LOCAL_CLUSTER */ const PWLBS_REG_PARAMS reg_data /* IN - Registry parameters. */ ); /* Write WLBS registry data. returns: WLBS_INIT_ERROR => Error initializing control module. Cannot perform control operations. WLBS_BAD_PARAMS => Registry parameter structure is invalid. WLBS_REG_ERROR => Error accessing the registry. Local: WLBS_OK => Registry parameters successfully written. Remote: WLBS_LOCAL_ONLY => This call is implemented for local only operation. */ extern DWORD WINAPI WlbsCommitChanges ( DWORD cluster /* IN - WLBS_LOCAL_CLUSTER */ ); /* Write WLBS registry data. returns: WLBS_INIT_ERROR => Error initializing control module. Cannot perform control operations. Local: WLBS_OK => Changes have been successfully applied. WLBS_BAD_PARAMS => Registry parameters were not accepted by the driver. Reload was not performed WLBS_REBOOT => Reboot required in order for config changes to take effect. WLBS_IO_ERROR => Error while writing to the driver. WLBS_REG_ERROR => Error while trying to write MAC address changes to the registry Remote: WLBS_LOCAL_ONLY => This call is implemented for local only operation. */ extern DWORD WINAPI WlbsSetDefaults ( PWLBS_REG_PARAMS reg_data /* OUT - Default values */ ); /* Fills in the reg_data structure with default values returns: WLBS_INIT_ERROR => Error initializing control module. Cannot perform control operations. WLBS_BAD_PARAMS => Invalid structure Local: WLBS_OK => Structure was filled in with the default values. Remote: WLBS_LOCAL_ONLY => This call is implemented for local only operation. */ /****************************************************************************** Registry parameter manipulation routines. Note that these routines operate WLBS_REG_PARAMS structure filled out by calling WlbsReadReg. Some parameters can be manipulated directly. Please make sure to use manipulation routines for the ones that they are provided for. ******************************************************************************/ extern DWORD WINAPI WlbsGetEffectiveVersion ( const PWLBS_REG_PARAMS reg_data /* IN - Registry parameters. */ ); /* Returns the effective version of cluster returns: CVY_VERSION_FULL => There is atleast one port rule that has a specific vip associated with it CVY_VERSION_LOWEST_CLIENT_FULL => All port rules have the "All vip" associated with them */ extern DWORD WINAPI WlbsGetNumPortRules ( const PWLBS_REG_PARAMS reg_data /* IN - Registry parameters. */ ); /* Returns number of port rules currently in the parameter structure. returns: WLBS_INIT_ERROR => Error initializing control module. Cannot perform control operations. WLBS_BAD_PARAMS => Registry parameter structure is invalid. 1...WLBS_MAX_RULES */ extern DWORD WINAPI WlbsEnumPortRules ( const PWLBS_REG_PARAMS reg_data, /* IN - Registry parameters. */ PWLBS_PORT_RULE rules, /* OUT - Array of port rules. */ PDWORD num_rules /* IN - Size of rules array. OUT - Number of rules retrieved. Note that this value can be larger than the size of the response array. In this case only the first few rules that fit in the array are returned. */ ); /* Enumerate all port rules in the list of port rules in parameter structure. returns: WLBS_INIT_ERROR => Error initializing control module. Cannot perform control operations. WLBS_BAD_PARAMS => Registry parameter structure is invalid. WLBS_TRUNCATED => All port rules did not fit into specified array. WLBS_OK => Rule has been successfully retrieved. */ extern DWORD WINAPI WlbsGetPortRule ( const PWLBS_REG_PARAMS reg_data, /* IN - Registry parameters. */ DWORD vip, /* IN - Virtual IP Address of the port rule to retreive */ DWORD port, /* IN - Port, which rule to retrieve. */ PWLBS_PORT_RULE rule /* OUT - Port rule. */ ); /* Retrieve port rule containing specified port from the list of port rules in parameter structure. returns: WLBS_INIT_ERROR => Error initializing control module. Cannot perform control operations. WLBS_BAD_PARAMS => Registry parameter structure is invalid. WLBS_OK => Rule has been successfully retrieved. WLBS_NOT_FOUND => Port not found among port rules. */ extern DWORD WINAPI WlbsAddPortRule ( PWLBS_REG_PARAMS reg_data, /* IN - Registry parameters. */ const PWLBS_PORT_RULE rule /* IN - Port rule to add. */ ); /* Add port to list of port rules in parameter structure. returns: WLBS_INIT_ERROR => Error initializing control module. Cannot perform control operations. WLBS_BAD_PARAMS => Registry parameter structure is invalid. WLBS_OK => Rule has been successfully added. WLBS_PORT_OVERLAP => Port rule overlaps with existing port rule. WLBS_BAD_PORT_PARAMS=> Invalid port rule parameters. WLBS_MAX_PORT_RULES => Maximum number of port rules already reached. */ extern DWORD WINAPI WlbsDeletePortRule ( PWLBS_REG_PARAMS reg_data, /* IN - Registry parameters. */ DWORD vip, /* IN - Virtual IP Address of the port rule to retreive */ DWORD port /* IN - Port, which rule to delete. */ ); /* Remove port rule containing specified port from the list of port rules in parameter structure. returns: WLBS_INIT_ERROR => Error initializing control module. Cannot perform control operations. WLBS_BAD_PARAMS => Registry parameter structure is invalid. WLBS_NOT_FOUND => Port not found among port rules. WLBS_OK => Rule has been successfully deleted. */ extern DWORD WINAPI WlbsSetRemotePassword ( PWLBS_REG_PARAMS reg_data, /* IN - Registry parameters. */ const WCHAR* password /* IN - Password or NULL for no password. */ ); /* Set remote password code to encrypted value of the specified password. returns: WLBS_INIT_ERROR => Error initializing control module. Cannot perform control operations. WLBS_BAD_PARAMS => Registry parameter structure is invalid. WLBS_OK => Password has been successfully set. */ DWORD WINAPI WlbsNotifyConfigChange(DWORD cluster); #ifdef __cplusplus } /* extern "C" */ #endif #endif _WLBSCONFIG_H