[MS-SWN]:
Service Witness Protocol
Intellectual Property Rights Notice for Open Specifications Documentation
§ Technical Documentation. Microsoft publishes Open Specifications documentation for protocols, file formats, languages, standards as well as overviews of the interaction among each of these technologies.
§ Copyrights. This documentation is covered by Microsoft copyrights. Regardless of any other terms that are contained in the terms of use for the Microsoft website that hosts this documentation, you may make copies of it in order to develop implementations of the technologies described in the Open Specifications and may distribute portions of it in your implementations using these technologies or your documentation as necessary to properly document the implementation. You may also distribute in your implementation, with or without modification, any schema, IDL’s, or code samples that are included in the documentation. This permission also applies to any documents that are referenced in the Open Specifications.
§ No Trade Secrets. Microsoft does not claim any trade secret rights in this documentation.
§ Patents. Microsoft has patents that may cover your implementations of the technologies described in the Open Specifications. Neither this notice nor Microsoft's delivery of the documentation grants any licenses under those or any other Microsoft patents. However, a given Open Specification may be covered by Microsoft Open Specification Promise or the Community Promise. If you would prefer a written license, or if the technologies described in the Open Specifications are not covered by the Open Specifications Promise or Community Promise, as applicable, patent licenses are available by contacting .
§ Trademarks. The names of companies and products contained in this documentation may be covered by trademarks or similar intellectual property rights. This notice does not grant any licenses under those rights. For a list of Microsoft trademarks, visit www.microsoft.com/trademarks.
§ Fictitious Names. The example companies, organizations, products, domain names, email addresses, logos, people, places, and events depicted in this documentation are fictitious. No association with any real company, organization, product, domain name, email address, logo, person, place, or event is intended or should be inferred.
Reservation of Rights. All other rights are reserved, and this notice does not grant any rights other than specifically described above, whether by implication, estoppel, or otherwise.
Tools. The Open Specifications do not require the use of Microsoft programming tools or programming environments in order for you to develop an implementation. If you have access to Microsoft programming tools and environments you are free to take advantage of them. Certain Open Specifications are intended for use in conjunction with publicly available standard specifications and network programming art, and assumes that the reader either is familiar with the aforementioned material or has immediate access to it.
Revision Summary
Date / Revision History / Revision Class / Comments /12/16/2011 / 1.0 / New / Released new document.
03/30/2012 / 2.0 / Major / Significantly changed the technical content.
07/12/2012 / 3.0 / Major / Significantly changed the technical content.
10/25/2012 / 4.0 / Major / Significantly changed the technical content.
01/31/2013 / 4.0 / No change / No changes to the meaning, language, or formatting of the technical content.
08/08/2013 / 5.0 / Major / Significantly changed the technical content.
2/2
[MS-SWN] — v20130722
Service Witness Protocol
Copyright © 2013 Microsoft Corporation.
Release: Monday, July 22, 2013
Contents
1 Introduction 5
1.1 Glossary 5
1.2 References 5
1.2.1 Normative References 5
1.2.2 Informative References 6
1.3 Overview 6
1.4 Relationship to Other Protocols 7
1.5 Prerequisites/Preconditions 7
1.6 Applicability Statement 7
1.7 Versioning and Capability Negotiation 8
1.8 Vendor Extensible Fields 8
1.9 Standards Assignments 8
2 Messages 9
2.1 Transport 9
2.2 Common Data Types 9
2.2.1 Data Types 9
2.2.1.1 PCONTEXT_HANDLE 10
2.2.1.2 PPCONTEXT_HANDLE 10
2.2.1.3 PCONTEXT_HANDLE_SHARED 10
2.2.2 Structures 10
2.2.2.1 IPADDR_INFO 10
2.2.2.2 IPADDR_INFO_LIST 11
2.2.2.3 RESOURCE_CHANGE 11
2.2.2.4 RESP_ASYNC_NOTIFY 12
2.2.2.5 WITNESS_INTERFACE_INFO 13
2.2.2.6 WITNESS_INTERFACE_LIST 14
3 Protocol Details 15
3.1 Witness Server Details 15
3.1.1 Abstract Data Model 15
3.1.1.1 Global 15
3.1.1.2 Per Interface in InterfaceList 15
3.1.1.3 Per WitnessRegistration in WitnessRegistrationList 15
3.1.1.4 Per Notification in PendingChangeNotifications 16
3.1.1.5 PendingMoveNotification 16
3.1.1.6 PendingShareMoveNotification 16
3.1.1.7 PendingIPNotification 16
3.1.2 Timers 17
3.1.2.1 Unused Registration Timer 17
3.1.2.2 AsyncNotify Pending Timer 17
3.1.3 Initialization 17
3.1.4 Message Processing Events and Sequencing Rules 17
3.1.4.1 WitnessrGetInterfaceList (Opnum 0) 18
3.1.4.2 WitnessrRegister (Opnum 1) 19
3.1.4.3 WitnessrUnRegister (Opnum 2) 21
3.1.4.4 WitnessrAsyncNotify (Opnum 3) 22
3.1.4.5 WitnessrRegisterEx (Opnum 4) 25
3.1.5 Timer Events 27
3.1.5.1 Unused Registration Timer Event 27
3.1.5.2 AsyncNotify Pending Timer Event 27
3.1.6 Other Local Events 27
3.1.6.1 Server Application Notifies of an Interface Being Enabled or Disabled 28
3.1.6.2 Server Application Notifies of a Request to Move to a New Resource 28
3.1.6.3 Server Application Notifies of a Change in the Resource that Owns a Share 28
3.1.6.4 Server Application Notifies of an IP Address Being Added, Removed, Enabled or Disabled 29
3.1.6.5 Transport Connection Shutdown 29
3.2 Witness Client Details 29
3.2.1 Abstract Data Model 29
3.2.1.1 Global 29
3.2.1.2 Per WitnessRegistration 29
3.2.2 Timers 30
3.2.3 Initialization 30
3.2.4 Message Processing Events and Sequencing Rules 30
3.2.4.1 Application Requests Witness Register 30
3.2.4.2 Application Requests Witness Event Notification 32
3.2.4.3 Application Requests Witness UnRegister 33
3.2.5 Timer Events 34
3.2.6 Other Local Events 34
4 Protocol Examples 35
5 Security 36
5.1 Security Considerations for Implementers 36
5.2 Index of Security Parameters 36
6 Appendix A: Full IDL 37
7 Appendix B: Product Behavior 39
8 Change Tracking 40
9 Index 44
2/2
[MS-SWN] — v20130722
Service Witness Protocol
Copyright © 2013 Microsoft Corporation.
Release: Monday, July 22, 2013
1 Introduction
The Service Witness Protocol is a remote procedure call (RPC)-based protocol that is used to promptly notify a client of resource changes that have occurred on a highly available server.
Sections 1.8, 2, and 3 of this specification are normative and can contain the terms MAY, SHOULD, MUST, MUST NOT, and SHOULD NOT as defined in RFC 2119. Sections 1.5 and 1.9 are also normative but cannot contain those terms. All other sections and examples in this specification are informative.
1.1 Glossary
The following terms are defined in [MS-GLOS]:
fully qualified domain name (FQDN)
IPv4
IPv6
Microsoft Interface Definition Language (MIDL)
NetBIOS name
remote procedure call (RPC)
RPC context handle
RPC server
RPC transport
Transmission Control Protocol (TCP)
UUID
The following terms are specific to this document:
MAY, SHOULD, MUST, SHOULD NOT, MUST NOT: These terms (in all caps) are used as described in [RFC2119]. All statements of optional behavior use either MAY, SHOULD, or SHOULD NOT.
1.2 References
References to Microsoft Open Specifications documentation do not include a publishing year because links are to the latest version of the documents, which are updated frequently. References to other documents include a publishing year when one is available.
A reference marked "(Archived)" means that the reference document was either retired and is no longer being maintained or was replaced with a new document that provides current implementation details. We archive our documents online [Windows Protocol].
1.2.1 Normative References
We conduct frequent surveys of the normative references to assure their continued availability. If you have any issue with finding a normative reference, please contact . We will assist you in finding the relevant information. Please check the archive site, http://msdn2.microsoft.com/en-us/library/E4BD6494-06AD-4aed-9823-445E921C9624, as an additional source.
[C706] The Open Group, "DCE 1.1: Remote Procedure Call", C706, August 1997, http://www.opengroup.org/public/pubs/catalog/c706.htm
[MS-DTYP] Microsoft Corporation, "Windows Data Types".
[MS-ERREF] Microsoft Corporation, "Windows Error Codes".
[MS-RPCE] Microsoft Corporation, "Remote Procedure Call Protocol Extensions".
[MS-SRVS] Microsoft Corporation, "Server Service Remote Protocol".
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997, http://www.rfc-editor.org/rfc/rfc2119.txt
1.2.2 Informative References
[MS-GLOS] Microsoft Corporation, "Windows Protocols Master Glossary".
[MS-SMB2] Microsoft Corporation, "Server Message Block (SMB) Protocol Versions 2 and 3".
1.3 Overview
In highly available systems, there can be many instances of a service (for instance an SMB3 file service [MS-SMB2]) running on a server or group of servers. These service instances are accessed by clients through network DNS names and associated IP addresses.
The Service Witness Protocol enables a client application (for instance, an SMB3 client) to receive prompt and explicit notifications about the failure or recovery of a network name and associated services, rather than relying on slower detection mechanisms such as timeouts and keep alives.
The Service Witness Protocol is an independent protocol which is used alongside other protocols, as illustrated by the following figure.
Figure 1: Witness clients communicating with Witness servers
1.4 Relationship to Other Protocols
This protocol depends on the RPC transport and uses RPC over TCP, as specified in section 2.1.
1.5 Prerequisites/Preconditions
The Service Witness Protocol is an RPC interface and, as a result, has the prerequisites that are described in [MS-RPCE] section 1.5 as being common to RPC interfaces.
1.6 Applicability Statement
This protocol applies in the following environments, where it is important that:
§ The client promptly detects when a resource has failed, and is now available for reconnection.
§ The administrator controls the client use of server resources, for instance, to achieve load- balancing or during server maintenance periods.
1.7 Versioning and Capability Negotiation
The protocol supports versioning negotiation. The current protocol supports two versions.
Version / Value /Witness protocol version 1 / 0x00010001
Witness protocol version 2 / 0x00020000
1.8 Vendor Extensible Fields
This protocol does not define any vendor-extensible fields.
This protocol uses Win32 error codes as defined in [MS-ERREF] section 2.2. Vendors SHOULD reuse those values with their indicated meaning. Choosing any other value runs the risk of a collision in the future.
1.9 Standards Assignments
Parameter / Value / Reference /UUID for Witness / ccd8c074-d0e5-4a40-92b4-d074faa6ba28 / [C706]
2 Messages
2.1 Transport
This protocol MUST use the UUID as specified in section 1.9. The RPC version number is 1.0.
This protocol allows any user to establish a connection to the RPC server. The protocol uses the underlying RPC protocol to retrieve the identity of the caller that made the method call, as specified in [MS-RPCE] section 3.3.3.4.3. The server SHOULD use this identity to perform method-specific access checks as specified in section 3.1.4.
2.2 Common Data Types
In addition to RPC base types defined in [C706] and [MS-RPCE], the data types that follow are defined in the Microsoft Interface Definition Language (MIDL) specification for this RPC interface.
The following data types are specified in [MS-DTYP]:
DataType name / Section /BOOLEAN / section 2.2.4
DWORD / section 2.2.9
LPWSTR / section 2.2.36
PBYTE / section 2.2.6
UINT / section 2.2.46
UINT32 / section 2.2.49
ULONG / section 2.2.51
USHORT / section 2.2.58
WCHAR / section 2.2.60
2.2.1 Data Types
DataType name / Section / Description /PCONTEXT_HANDLE / 2.2.1.1 / An RPC context handle returned by the WitnessrRegister method, to be provided as an input parameter to the WitnessrUnRegister method.
PCONTEXT_HANDLE_SHARED / 2.2.1.3 / An RPC context handle returned by the WitnessrRegister method, to be provided as an input parameter to the WitnessrAsyncNotify method.
PPCONTEXT_HANDLE / 2.2.1.2 / A reference to PCONTEXT_HANDLE.
2.2.1.1 PCONTEXT_HANDLE
PCONTEXT_HANDLE: An RPC context handle, as specified in [C706] Chapter 6, returned by the WitnessrRegister method, to be provided as an input parameter to the WitnessrUnRegister method.
typedef [context_handle] void* PCONTEXT_HANDLE;
2.2.1.2 PPCONTEXT_HANDLE
PPCONTEXT_HANDLE: A reference to PCONTEXT_HANDLE, as specified in section 2.2.1.1.
typedef [ref] PCONTEXT_HANDLE *PPCONTEXT_HANDLE;
2.2.1.3 PCONTEXT_HANDLE_SHARED
PCONTEXT_HANDLE_SHARED: An RPC context handle, as specified in [C706] Chapter 6, returned by the WitnessrRegister method, to be provided as a parameter to the WitnessrAsyncNotify method.
typedef [context_handle] PCONTEXT_HANDLE PCONTEXT_HANDLE_SHARED;
2.2.2 Structures
Structure name / Section / Description /IPADDR_INFO / 2.2.2.1 / The IPADDR_INFO structure specifies the IP addresses of the interface.
IPADDR_INFO_LIST / 2.2.2.2 / The IPADDR_INFO_LIST structure contains the list of available IP addresses on the destination Interface group.
RESOURCE_CHANGE / 2.2.2.3 / The server notifies the registered client of resource state changes through the RESOURCE_CHANGE structure.
RESP_ASYNC_NOTIFY / 2.2.2.4 / The RESP_ASYNC_NOTIFY structure contains the resource change type.
WITNESS_INTERFACE_INFO / 2.2.2.5 / The WITNESS_INTERFACE_INFO structure specifies the IP addresses of the interface.
WITNESS_INTERFACE_LIST / 2.2.2.6 / The WITNESS_INTERFACE_LIST structure specifies the list of interfaces available for witness registration.
2.2.2.1 IPADDR_INFO
The IPADDR_INFO structure specifies the IP addresses of the interface.
typedef struct _IPADDR_INFO {
UINT Flags;
ULONG IPV4;
USHORT IPV6[8];
} IPADDR_INFO, *PIPADDR_INFO;
Flags: The Flags field MUST be set to a combination of one or more of the following values.
Value / Description /0x00000001
IPADDR_V4 / If set, the IPV4 field contains a valid address. When this bit is set, the IPADDR_IPV6 bit MUST NOT be set.
0x00000002
IPADDR_V6 / If set, the IPV6 field contains a valid address. When this bit is set, the IPADDR_IPV4 bit MUST NOT be set.
0x00000008
IPADDR_ONLINE / If set, the IPV4 or IPV6 address is available. This flag is applicable only for the servers implementing version 2.
0x00000010
IPADDR_OFFLINE / If set, the IPV4 or IPV6 address is not available. This flag is applicable only for the server implementing version 2.
IPV4: The IPv4 address of the interface.
IPV6: The IPv6 address of the interface.
2.2.2.2 IPADDR_INFO_LIST
The IPADDR_INFO_LIST structure contains a list of available IP addresses on the destination Interface group.
typedef struct _IPADDR_INFO_LIST {
UINT Length;
ULONG Reserved;
ULONG IPAddrInstances;
IPADDR_INFO IPAddrInfo[];
} IPADDR_INFO_LIST, *PIPADDR_INFO_LIST;
Length: The size of the IPADDR_INFO_LIST structure, in bytes.
Reserved: This field MUST NOT be used and MUST be reserved. The server MUST set this field to 0, and the client MUST ignore it on receipt.