Merge pull request #22177 from PiJoCoder/ListenerPort_JoPilov052322

jborsecnik · web-flow · commit bc01a0686dc8 · 2022-05-26T14:00:24.000-07:00
Organizing the AG Listener paragraph a bit and adding exercise/demo of how it works
diff --git a/docs/database-engine/availability-groups/windows/availability-group-listener-overview.md b/docs/database-engine/availability-groups/windows/availability-group-listener-overview.md
@@ -4,7 +4,7 @@ description: "An overview of the Always On availability group listener and how i
 ms.custom:
   - seodec18
   - intro-overview
-ms.date: "02/27/2020"
+ms.date: "05/23/2022"
 ms.prod: sql
 ms.reviewer: ""
 ms.technology: availability-groups
@@ -24,7 +24,7 @@ ms.author: mathoma
 # What is an availability group listener?  
 [!INCLUDE [SQL Server](../../../includes/applies-to-version/sqlserver.md)]
 
-An availability group listener is a virtual network name (VNN) that clients can connect to in order to access a database in a primary or secondary replica of an Always On availability group. A listener allows a client to connect to a replica without having to know the physical instance name of the SQL Server. Since the listener routes traffic, the client connection string does not need to be modified after a failover occurs. 
+An availability group listener is a virtual network name (VNN) that clients can connect to in order to access a database in a primary or secondary replica of an Always On availability group. A listener allows a client to connect to a replica without having to know the physical instance name of the SQL Server. Since the listener routes traffic, the client connection string doesn't need to be modified after a failover occurs. 
 
 An availability group listener consists of a Domain Name System (DNS) listener name, listener port designation, and one or more IP addresses. Only the TCP protocol is supported by availability group listener.  The DNS name of the listener must be unique in the domain and in NetBIOS.  When you create a  listener, it becomes a resource in a cluster with an associated virtual network name (VNN), virtual IP (VIP), and availability group dependency. A client uses DNS to resolve the VNN into multiple IP addresses and then tries to connect to each address, until a connection request succeeds or until the connection requests time out.  
   
@@ -48,13 +48,52 @@ This article provides an overview of an availability group listener. You can als
  
   
 ##  <a name="SelectListenerPort"></a> Listener port 
- When configuring an availability group listener, you must designate a port.  You can configure the default port to 1433 in order to allow for simplicity of the client connection strings. If using 1433, you do not need to designate a port number in a connection string. Also, since each availability group listener will have a separate virtual network name, each availability group listener configured on a single WSFC can be configured to reference the same default port of 1433.  
-  
- You can also designate a non-standard listener port; however this means that you will also need to explicitly specify a target port in your connection string whenever connecting to the availability group listener.  You will also need to open permission on the firewall for the non-standard port.  
-  
- If you use the default port of 1433 for availability group listener VNNs, you will still need to ensure that no other services on the cluster node are using this port; otherwise this would cause a port conflict.  
-  
- If one of the instances of SQL Server is already listening on TCP port 1433 via the instance listener and there are no other services (including additional instances of SQL Server) on the computer listening on port 1433, this will not cause a port conflict with the availability group listener.  This is because the availability group listener can share the same TCP port inside the same service process.  However multiple instances of SQL Server (side-by-side) should not be configured to listen on the same port.  
+ When configuring an availability group listener, you must designate a port via SSMS.  You can configure the default port to 1433 in order to allow for simplicity of the client connection strings. This means, that if you use 1433, you don't need to include a port number in a connection string of your application. Also, since each availability group listener will have a separate virtual network name, each availability group listener configured on a single WSFC can be configured to reference the same default port of 1433.  
+
+ If you use the default port of 1433 for availability group listener VNNs, you'll still need to ensure that no other services on the cluster node are using this port; otherwise this would cause a port conflict. 
+
+ If one of the instances of SQL Server is already listening on TCP port 1433 via the instance listener and there are no other services (including additional instances of SQL Server) on the computer listening on port 1433, this won't cause a port conflict with the availability group listener.  This is because the availability group listener can share the same TCP port inside the same process.  However multiple instances of SQL Server (side-by-side) must not be configured to listen on the same port because one of them will fail to listen for connections.  
+
+ You can also designate a non-standard availability group listener port. However, you also need to explicitly use the target port in your application connection string when connecting to a listener.  You also need to open permission on the firewall for this port.  
+
+ You can connect to the listener using the name and port (if not 1433). The port can be either the listener port or the underlying SQL Server port that it's configured to listen on. 
+
+ The following examples demonstrate some of the functionality of the listener:
+ 
+ **Set up:**
+ - IP that SQL Server is listening on: 192.168.20.2
+ - Port that SQL Server is listening on: 50254
+ - Listener IP that was configured: 192.168.20.15
+ - Listener name was configured: aglistener19
+ - Listener port that was configured: 50123
+ 
+1. Connect to the listener via IP address and port. This connection is successful. 
+
+   ```console
+   sqlcmd -S 192.168.20.15,50123 
+   1> 
+   ```
+
+ 1. Connect to the listener by name only, no port. This connection will fail because a non-default port was used. You must specify that port. 
+
+    ```console
+    sqlcmd -S aglistener19 
+    ```
+
+ 1.	Connect to the listener by listener name and configured port. This connection is successful.
+
+    ```console
+    sqlcmd -S aglistener19,50123 
+    1> 
+    ```
+
+
+ 1. Finally, connect to the listener and the SQL Server port. Notice that in this case you're using the port SQL Server is listening on, not the listener port. This connection also succeeds.
+
+    ```console
+    sqlcmd -S aglistener19,50254
+    1> 
+    ```
   
   
 ##  <a name="CCBehaviorOnFailover"></a> Behavior of client connections on failover  
diff --git a/docs/database-engine/availability-groups/windows/troubleshoot-always-on-availability-groups-configuration-sql-server.md b/docs/database-engine/availability-groups/windows/troubleshoot-always-on-availability-groups-configuration-sql-server.md
@@ -27,10 +27,11 @@ ms.author: mathoma
   
 |Section|Description|  
 |-------------|-----------------|  
-|[Always On Availability Groups Is Not Enabled](#IsHadrEnabled)|If an instance of [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)] is not enabled for [!INCLUDE[ssHADR](../../../includes/sshadr-md.md)], the instance doesn't support availability group creation and cannot host any availability replicas.|  
+|[Always On Availability Groups Isn't Enabled](#IsHadrEnabled)|If an instance of [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)] is not enabled for [!INCLUDE[ssHADR](../../../includes/sshadr-md.md)], the instance doesn't support availability group creation and can't host any availability replicas.|  
 |[Accounts](#Accounts)|Discusses requirements for correctly configuring the accounts under which [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)] is running.|  
 |[Endpoints](#Endpoints)|Discusses how to diagnose issues with the database mirroring endpoint of a server instance.|  
 |[Network access](#NetworkAccess)|Documents the requirement that each server instance that is hosting an availability replica must be able to access the port of each of the other server instances over TCP.|  
+|[Listener](#Listener)|Documents how to establish the IP address and port of the listener and make sure it is running and listening for incoming connections|  
 |[Endpoint Access (SQL Server Error 1418)](#Msg1418)|Contains information about this [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)] error message.|  
 |[Join Database Fails (SQL Server Error 35250)](#JoinDbFails)|Discusses the possible causes and resolution of a failure to join secondary databases to an availability group because the connection to the primary replica isn't active.|  
 |[Read-Only Routing is Not Working Correctly](#ROR)||  
@@ -108,7 +109,7 @@ For more information, see [Enable and Disable Always On Availability Groups &#40
     GO  
     ```  
   
-3.  For [!INCLUDE[ssHADR](../../../includes/sshadr-md.md)] setup issues that are difficult to explain, we recommend that you inspect each server instance to determine whether it is listening on the correct ports.  
+3.  For [!INCLUDE[ssHADR](../../../includes/sshadr-md.md)] setup issues that are difficult to explain, we recommend that you inspect each server instance to determine whether it's listening on the correct ports.  
   
 4.  Make sure that the endpoints are started (STATE=STARTED). On each server instance, use the following [!INCLUDE[tsql](../../../includes/tsql-md.md)] statement:  
   
@@ -155,17 +156,20 @@ For more information, see [Enable and Disable Always On Availability Groups &#40
     select endpoint_url from sys.availability_replicas
     ```
 
-    Next, compare the endpoint_url output to the server name (Netbios or FQDN).
-    To query the Netbios and FQDN, run the following command in a Command Prompt on the replica locally:
+    Next, compare the endpoint_url output to the server name (NetBIOS name or FQDN).
+    To query the server name, run the following commands in a PowerShell on the replica locally:
 
-    ```dos
-    hostname & echo %COMPUTERNAME%.%USERDNSDOMAIN%
+    ```PowerShell
+    $env:COMPUTERNAME
+    [System.Net.Dns]::GetHostEntry([string]$env:computername).HostName
     ```
 
-    For query the server name of a remote computer, run this command from a Command Prompt. Then compare the endpoint_url
+    To validate the server name on a remote computer, run this command from PowerShell. 
 
-    ```dos
-    ping -a servername_from_endpoint_url
+    ```PowerShell
+    $servername_from_endpoint_url = "server_from_endpoint_url_output"
+
+    Test-NetConnection -ComputerName $servername_from_endpoint_url
     ```
 
 
@@ -174,11 +178,16 @@ For more information, see [Enable and Disable Always On Availability Groups &#40
 ##  <a name="NetworkAccess"></a> Network Access  
  Each server instance that is hosting an availability replica must be able to access the port of each of the other server instance over TCP. This is especially important if the server instances are in different domains that don't trust each other (untrusted domains).  Check if you can connect to the endpoints by following these steps:
 
-- Use Telnet to validate connectivity. Here are examples of commands you can use:
+- Use Test-NetConnection (equivalent to Telnet)  to validate connectivity. Here are examples of commands you can use:
+
+   ```PowerShell
+   $server_name = "your_server_name"
+   $IP_address = "your_ip_address"
+   $port_number = "your_port_number"
 
-   ```DOS
-   telnet ServerName Port
-   telnet IP_Address Port
+   Test-NetConnection -ComputerName $server_name -Port $port_number
+   Test-NetConnection -ComputerName $IP_address -Port $port_number
+   ```
 
 - If the Endpoint is listening and connection is successful, then you'll see a blank screen.  If not, you'll receive a connection error from Telnet
 - If Telnet connection to the IP address works but to the ServerName it doesn't, there's likely a DNS or name resolution issue
@@ -189,15 +198,59 @@ Run the following PowerShell script to examine for disabled inbound traffic rule
 
    ```powershell
    Get-NetFirewallRule -Action Block -Enabled True -Direction Inbound |Format-Table
+   ```
+
+- Capture the output from Get-NetTCPConnection cmdlet (equivalent of NETSTAT -a) and verify the status is a LISTENING or ESTABLISHED on the IP:Port for the endpoint specified
+
+   ```PowerShell
+   Get-NetTCPConnection 
+   ```
+
+
+##  <a name="Listener"></a> Listener
 
-- Capture a NETSTAT -a output and verify the status is a LISTENING or ESTABLISHED on the IP:Port for the endpoint specified
+For correct configuration of an Availability Group listener follow "[Configure a listener for an Always On availability group](create-or-configure-an-availability-group-listener-sql-server.md)"
 
-   ```dos
-   netstat -a
+1. Once the listener is configured you can validate the IP address and port it is listening on by using the following query:
+
+   ```PowerShell
+   $server_name = $env:computername  #replace this with your sql instance "server\instance"
+
+   sqlcmd -E -S$server_name -Q"SELECT dns_name AS AG_listener_name, port, ip_configuration_string_from_cluster 
+   FROM sys.availability_group_listeners"
+   ```
 
+1. You can also find the listener information together with the SQL Server ports using this query:
+ 
+   ```PowerShell
+   $server_name = $env:computername      #replace this with your sql instance "server\instance"
+
+   sqlcmd -E -S($server_name) -Q("SELECT  convert(varchar(32), SERVERPROPERTY ('servername')) servername, convert(varchar(32),ip_address) ip_address, port, type_desc,state_desc, start_time 
+   FROM sys.dm_tcp_listener_states 
+   WHERE ip_address not in ('127.0.0.1', '::1') and type <> 2")
+   ```
+
+1. If you need to establish connectivity to the listener and suspect a port is blocked, you can perform a test using the PowerShell Test-NetConnection cmdlet (equivalent to telnet). 
+
+   ```PowerShell
+   $listener_name = "your_ag_listener"
+   $IP_address = "your_ip_address"
+   $port_number = "your_port_number"
+
+   Test-NetConnection -ComputerName $listener_name -Port $port_number
+   Test-NetConnection -ComputerName $IP_address -Port $port_number
+   ```
+
+1. Finally, check if the listener is listening on the specified port:
+
+   ```PowerShell
+   $port_number = "your_port_number"
+
+   Get-NetTCPConnection -LocalPort $port_number -State Listen
+   ```
   
 ##  <a name="Msg1418"></a> Endpoint Access (SQL Server Error 1418)  
- This [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)] message indicates that the server network address specified in the endpoint URL cannot be reached or doesn't exist, and it suggests that you verify the network address name and reissue the command.  
+ This [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)] message indicates that the server network address specified in the endpoint URL can't be reached or doesn't exist, and it suggests that you verify the network address name and reissue the command.  
   
 ##  <a name="JoinDbFails"></a> Join Database Fails (SQL Server Error 35250)  
  This section discusses the possible causes and resolution of a failure to join secondary databases to the availability group because the connection to the primary replica isn't active. This is the full error message:
@@ -300,7 +353,7 @@ For **detailed** step-by-step instructions, refer to Engine error [MSSQLSERVER_3
    >[!NOTE]
    > If you are running [!INCLUDE[ssNoVersion](../../../includes/ssnoversion-md.md)] on Azure VM, you must take additional configuration steps. Ensure that the network security group (NSG) of each replica VM allows traffic to the endpoint port and the DNN port, if you are using DNN listener. If you are using VNN listener, you must ensure the [load balancer is configured correctly](/azure/azure-sql/virtual-machines/windows/availability-group-load-balancer-portal-configure).
 
-7. Ensure that the READ_ONLY_ROUTING_URL (TCP://system-address:port) contains the correct fully-qualified domain name (FQDN) and port number. See:  
+7. Ensure that the READ_ONLY_ROUTING_URL (TCP://system-address:port) contains the correct fully qualified domain name (FQDN) and port number. See:  
    - [Calculating read_only_routing_url for Always On](/archive/blogs/mattn/calculating-read_only_routing_url-for-alwayson) 
    - [sys.availability_replicas (Transact-SQL)](../../../relational-databases/system-catalog-views/sys-availability-replicas-transact-sql.md)
    - [ALTER AVAILABILITY GROUP (Transact-SQL)](../../../t-sql/statements/alter-availability-group-transact-sql.md) 
