[MS-SWN]:
Service Witness Protocol
Intellectual Property Rights Notice for Open Specifications Documentation
Technical Documentation. Microsoft publishes Open Specifications documentation (“this documentation”) for protocols, file formats, data portability, computer languages, and standards support. Additionally, overview documents cover inter-protocol relationships and interactions.
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 can make copies of it in order to develop implementations of the technologies that are described in this documentation and can distribute portions of it in your implementations that use these technologies or in your documentation as necessary to properly document the implementation. You can also distribute in your implementation, with or without modification, any schemas, IDLs, or code samples that are included in the documentation. This permission also applies to any documents that are referenced in the Open Specifications documentation.
No Trade Secrets. Microsoft does not claim any trade secret rights in this documentation.
Patents. Microsoft has patents that might cover your implementations of the technologies described in the Open Specifications documentation. Neither this notice nor Microsoft's delivery of this documentation grants any licenses under those patents or any other Microsoft patents. However, a given Open Specifications document might be covered by the Microsoft Open Specifications Promise or the Microsoft Community Promise. If you would prefer a written license, or if the technologies described in this documentation are not covered by the Open Specifications Promise or Community Promise, as applicable, patent licenses are available by contacting .
License Programs. To see all of the protocols in scope under a specific license program and the associated patents, visit the Patent Map.
Trademarks. The names of companies and products contained in this documentation might 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
Fictitious Names. The example companies, organizations, products, domain names, email addresses, logos, people, places, and events that are 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 as specifically described above, whether by implication, estoppel, or otherwise.
Tools. The Open Specifications documentation does 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 documents are intended for use in conjunction with publicly available standards specifications and network programming art and, as such, assume that the reader either is familiar with the aforementioned material or has immediate access to it.
Support. For questions and support, please contact .
Revision Summary
Date / Revision History / Revision Class / Comments12/16/2011 / 1.0 / New / Released new document.
3/30/2012 / 2.0 / Major / Significantly changed the technical content.
7/12/2012 / 3.0 / Major / Significantly changed the technical content.
10/25/2012 / 4.0 / Major / Significantly changed the technical content.
1/31/2013 / 4.0 / None / No changes to the meaning, language, or formatting of the technical content.
8/8/2013 / 5.0 / Major / Significantly changed the technical content.
11/14/2013 / 6.0 / Major / Significantly changed the technical content.
2/13/2014 / 7.0 / Major / Significantly changed the technical content.
5/15/2014 / 7.0 / None / No changes to the meaning, language, or formatting of the technical content.
6/30/2015 / 8.0 / Major / Significantly changed the technical content.
10/16/2015 / 8.0 / None / No changes to the meaning, language, or formatting of the technical content.
7/14/2016 / 9.0 / Major / Significantly changed the technical content.
6/1/2017 / 9.0 / None / No changes to the meaning, language, or formatting of the technical content.
9/15/2017 / 10.0 / Major / Significantly changed the technical content.
12/1/2017 / 10.0 / None / No changes to the meaning, language, or formatting of the technical content.
Table of Contents
1Introduction
1.1Glossary
1.2References
1.2.1Normative References
1.2.2Informative References
1.3Overview
1.4Relationship to Other Protocols
1.5Prerequisites/Preconditions
1.6Applicability Statement
1.7Versioning and Capability Negotiation
1.8Vendor Extensible Fields
1.9Standards Assignments
2Messages
2.1Transport
2.2Common Data Types
2.2.1Data Types
2.2.1.1PCONTEXT_HANDLE
2.2.1.2PPCONTEXT_HANDLE
2.2.1.3PCONTEXT_HANDLE_SHARED
2.2.2Structures
2.2.2.1IPADDR_INFO
2.2.2.2IPADDR_INFO_LIST
2.2.2.3RESOURCE_CHANGE
2.2.2.4RESP_ASYNC_NOTIFY
2.2.2.5WITNESS_INTERFACE_INFO
2.2.2.6WITNESS_INTERFACE_LIST
3Protocol Details
3.1Witness Server Details
3.1.1Abstract Data Model
3.1.1.1Global
3.1.1.2Per Interface in InterfaceList
3.1.1.3Per WitnessRegistration in WitnessRegistrationList
3.1.1.4Per Notification in PendingChangeNotifications
3.1.1.5PendingMoveNotification
3.1.1.6PendingShareMoveNotification
3.1.1.7PendingIPNotification
3.1.2Timers
3.1.2.1Unused Registration Timer
3.1.2.2AsyncNotify Pending Timer
3.1.3Initialization
3.1.4Message Processing Events and Sequencing Rules
3.1.4.1WitnessrGetInterfaceList (Opnum 0)
3.1.4.2WitnessrRegister (Opnum 1)
3.1.4.3WitnessrUnRegister (Opnum 2)
3.1.4.4WitnessrAsyncNotify (Opnum 3)
3.1.4.5WitnessrRegisterEx (Opnum 4)
3.1.5Timer Events
3.1.5.1Unused Registration Timer Event
3.1.5.2AsyncNotify Pending Timer Event
3.1.6Other Local Events
3.1.6.1Server Application Notifies of an Interface Being Enabled or Disabled
3.1.6.2Server Application Notifies of a Request to Move to a New Resource
3.1.6.3Server Application Notifies of a Change in the Resource that Owns a Share
3.1.6.4Server Application Notifies of an IP Address Being Added, Removed, Enabled or Disabled
3.1.6.5Transport Connection Shutdown
3.2Witness Client Details
3.2.1Abstract Data Model
3.2.1.1Global
3.2.1.2Per WitnessRegistration
3.2.2Timers
3.2.3Initialization
3.2.4Message Processing Events and Sequencing Rules
3.2.4.1Application Requests Witness Register
3.2.4.2Application Requests Witness Event Notification
3.2.4.3Application Requests Witness UnRegister
3.2.5Timer Events
3.2.6Other Local Events
4Protocol Examples
4.1Registering Notification Changes from the Witness Server
5Security
5.1Security Considerations for Implementers
5.2Index of Security Parameters
6Appendix A: Full IDL
7Appendix B: Product Behavior
8Change Tracking
9Index
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.5, 1.8, 1.9, 2, and 3 of this specification are normative. All other sections and examples in this specification are informative.
1.1 Glossary
This document uses the following terms:
fully qualified domain name (FQDN): An unambiguous domain name that gives an absolute location in the Domain Name System's (DNS) hierarchy tree, as defined in [RFC1035] section 3.1 and [RFC2181] section 11.
Internet Protocol version 4 (IPv4): An Internet protocol that has 32-bit source and destination addresses. IPv4 is the predecessor of IPv6.
Internet Protocol version 6 (IPv6): A revised version of the Internet Protocol (IP) designed to address growth on the Internet. Improvements include a 128-bit IP address size, expanded routing capabilities, and support for authentication and privacy.
Microsoft Interface Definition Language (MIDL): The Microsoft implementation and extension of the OSF-DCE Interface Definition Language (IDL). MIDL can also mean the Interface Definition Language (IDL) compiler provided by Microsoft. For more information, see [MS-RPCE].
NetBIOS name: A 16-byte address that is used to identify a NetBIOS resource on the network. For more information, see [RFC1001] and [RFC1002].
remote procedure call (RPC): A communication protocol used primarily between client and server. The term has three definitions that are often used interchangeably: a runtime environment providing for communication facilities between computers (the RPC runtime); a set of request-and-response message exchanges between computers (the RPC exchange); and the single message from an RPC exchange (the RPC message). For more information, see [C706].
RPC context handle: A representation of state maintained between a remote procedure call (RPC) client and server. The state is maintained on the server on behalf of the client. An RPC context handle is created by the server and given to the client. The client passes the RPC context handle back to the server in method calls to assist in identifying the state. For more information, see [C706].
RPC server: A computer on the network that waits for messages, processes them when they arrive, and sends responses using RPC as its transport acts as the responder during a remote procedure call (RPC) exchange.
RPC transport: The underlying network services used by the remote procedure call (RPC) runtime for communications between network nodes. For more information, see [C706] section 2.
Transmission Control Protocol (TCP): A protocol used with the Internet Protocol (IP) to send data in the form of message units between computers over the Internet. TCP handles keeping track of the individual units of data (called packets) that a message is divided into for efficient routing through the Internet.
universally unique identifier (UUID): A 128-bit value. UUIDs can be used for multiple purposes, from tagging objects with an extremely short lifetime, to reliably identifying very persistent objects in cross-process communication such as client and server interfaces, manager entry-point vectors, and RPC objects. UUIDs are highly likely to be unique. UUIDs are also known as globally unique identifiers (GUIDs) and these terms are used interchangeably in the Microsoft protocol technical documents (TDs). Interchanging the usage of these terms does not imply or require a specific algorithm or mechanism to generate the UUID. Specifically, the use of this term does not imply or require that the algorithms described in [RFC4122] or [C706] must be used for generating the UUID.
MAY, SHOULD, MUST, SHOULD NOT, MUST NOT: These terms (in all caps) are used as defined in [RFC2119]. All statements of optional behavior use either MAY, SHOULD, or SHOULD NOT.
1.2 References
Links to a document in the Microsoft Open Specifications library point to the correct section in the most recently published version of the referenced document. However, because individual documents in the library are not updated at the same time, the section numbers in the documents may not match. You can confirm the correct section numbering by checking the Errata.
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.
[C706] The Open Group, "DCE 1.1: Remote Procedure Call", C706, August 1997,
[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,
1.2.2 Informative References
[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 time-outs 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 / ValueWitness 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 / ReferenceUUID 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 / SectionBOOLEAN / 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 / DescriptionPCONTEXT_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
Unless otherwise specified, multiple-byte fields (16-bit, 32-bit, and 64-bit fields) MUST be transmitted in little-endian order (least-significant byte first) for the structures specified in section 2.2.2.1 (IPADDR_INFO), 2.2.2.2 (IPADDR_INFO_LIST), and 2.2.2.3 (RESOURCE_CHANGE). Other structures defined in this section use RPC encoding.
Structure name / Section / DescriptionIPADDR_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.
0 / 1 / 2 / 3 / 4 / 5 / 6 / 7 / 8 / 9 / 10 / 1 / 2 / 3 / 4 / 5 / 6 / 7 / 8 / 9 / 2
0 / 1 / 2 / 3 / 4 / 5 / 6 / 7 / 8 / 9 / 3
0 / 1
Flags
IPV4
IPV6 (16 bytes)
...
...
Flags (4 bytes): The Flags field SHOULD<1> be set to a combination of one or more of the following values.
Value / Description0x00000001
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 (4 bytes): The IPv4 address of the interface, if the IPADDR_V4 flag is set in the Flags field.
IPV6 (16 bytes): The IPv6 address of the interface, if the IPADDR_V6 flag is set in the Flags field.
2.2.2.2 IPADDR_INFO_LIST
The IPADDR_INFO_LIST structure contains a list of available IP addresses on the destination Interface group.
0 / 1 / 2 / 3 / 4 / 5 / 6 / 7 / 8 / 9 / 10 / 1 / 2 / 3 / 4 / 5 / 6 / 7 / 8 / 9 / 2
0 / 1 / 2 / 3 / 4 / 5 / 6 / 7 / 8 / 9 / 3
0 / 1
Length
Reserved
IPAddrInstances
IPAddrInfo (variable)
...
...
Length (4 bytes): The size of the IPADDR_INFO_LIST structure, in bytes.
Reserved (4 bytes): 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.
IPAddrInstances (4 bytes): The number of IPADDR_INFO structures in the IPAddrInfo member.
IPAddrInfo (variable): An array of one or more IPADDR_INFO structures, as specified in section 2.2.2.1, indicating the IP addresses of the destination Interface group.
2.2.2.3 RESOURCE_CHANGE
The server notifies the registered client of resource state changes through the use of the RESOURCE_CHANGE structure.
0 / 1 / 2 / 3 / 4 / 5 / 6 / 7 / 8 / 9 / 10 / 1 / 2 / 3 / 4 / 5 / 6 / 7 / 8 / 9 / 2
0 / 1 / 2 / 3 / 4 / 5 / 6 / 7 / 8 / 9 / 3
0 / 1
Length
ChangeType
ResourceName (variable)
...
...
Length (4 bytes): The size of the resource change notification, in bytes.
ChangeType (4 bytes): Specifies state change of the resource. The following values are used to specify the change type.
Value / Meaning0x00000000 / RESOURCE_STATE_UNKNOWN
0x00000001 / RESOURCE_STATE_AVAILABLE
0x000000FF / RESOURCE_STATE_UNAVAILABLE
ResourceName (variable): The null terminated resource name on which the change has been detected. This MUST be either the NetName or IP address provided in a WitnessrRegister call, or an InterfaceGroupName returned to the client in a WitnessrGetInterfaceList response.
2.2.2.4 RESP_ASYNC_NOTIFY
The RESP_ASYNC_NOTIFY structure contains the resource change type.
typedef struct _RESP_ASYNC_NOTIFY {
UINT MessageType;
UINT Length;
UINT NumberOfMessages;
[size_is(Length)] [unique] PBYTE MessageBuffer;
} RESP_ASYNC_NOTIFY, *PRESP_ASYNC_NOTIFY;
MessageType: Specifies the notification type. This field MUST contain one of the following values.
Value / Meaning1 / RESOURCE_CHANGE_NOTIFICATION
2 / CLIENT_MOVE_NOTIFICATION
3 / SHARE_MOVE_NOTIFICATION
This value is applicable only for the server implementing version 2.
4 / IP_CHANGE_NOTIFICATION
This value is applicable only for the server implementing version 2.
Length: Specifies the size of the MessageBuffer field, in bytes.
NumberOfMessages: Total number of notifications in the MessageBuffer field.
MessageBuffer: Contains an array of notification information structures whose type is determined by the MessageType field.
2.2.2.5 WITNESS_INTERFACE_INFO
The WITNESS_INTERFACE_INFO structure specifies the IP addresses of the interface.
typedef struct _WITNESS_INTERFACE_INFO {
WCHAR InterfaceGroupName[260];
ULONG Version;
USHORT State;
ULONG IPV4;
USHORT IPV6[8];
UINT Flags;
} WITNESS_INTERFACE_INFO, *PWITNESS_INTERFACE_INFO;
InterfaceGroupName: The null-terminated string that specifies a name of the interface group.
Version: The current version of the Witness Service running on the server.
State: The current state of the interface. This field MUST contain one of the following values:
Value / MeaningUNKNOWN
0x0000 / The state of the interface is unknown.
AVAILABLE
0x0001 / The interface is available.
UNAVAILABLE
0x00FF / The interface is unavailable.
IPV4: The IPv4 address of the interface, if the IPv4 flag is set in Flags field.
IPV6: The IPv6 address of the interface, if the IPv6 flag is set in Flags field.
Flags: The Flags field specifies information about the interface. This field MUST be set to combination of zero or more of the following values:
Value / MeaningIPv4
0x00000001 / If set, the IPV4 field contains a valid address.
IPv6
0x00000002 / If set, the IPV6 field contains a valid address.
INTERFACE_WITNESS
0x00000004 / If set, the interface is available for witness registration. If not set, the interface MUST NOT be used for witness registration.
2.2.2.6 WITNESS_INTERFACE_LIST
The WITNESS_INTERFACE_LIST structure specifies the list of interfaces available for witness registration.