Creates a new static phone route.
Syntax
New-CsStaticRoute -Destination <String> -MatchUri <String> -Port <UInt16> -TLSRoute <SwitchParameter> [-Enabled <$true | $false>] [-MatchOnlyPhoneUri <$true | $false>] [-ReplaceHostInRequestUri <$true | $false>] [-TLSCertIssuer <String>] [-TLSCertSerialNumber <Byte[]>] [-UseDefaultCertificate <$true | $false>] |
New-CsStaticRoute -Destination <String> -MatchUri <String> -Port <UInt16> -TCPRoute <SwitchParameter> [-Enabled <$true | $false>] [-MatchOnlyPhoneUri <$true | $false>] [-ReplaceHostInRequestUri <$true | $false>] |
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
|
TLSRoute |
Optional |
Switch Parameter |
Configures TLS (Transport Layer Security) as the transport protocol for the new route. |
|
TCPRoute |
Optional |
Switch Parameter |
Configures TCP (Transmission Control Protocol) as the transport protocol for the new route. |
|
Destination |
Required |
String |
If the route uses TLS as the transport protocol then the Destination is the fully qualified domain name of the next hop server. For example: -Destination atl-proxy-001.litwareinc.com. If the route uses TCP as the transport protocol then the Destination is the IP address of the next hop router. For example: -Destination 192.168.0.240. |
|
Port |
Required |
Integer |
Port number used for SIP routing. For example: -Port 7742. |
|
Enabled |
Optional |
Boolean |
If set to True ($True) then the route is enabled, and any messages matching the MatchURI pattern will be routed to the next hop server. If set to False, the route is disabled and will not be used in routing messages. The default value is True. |
|
MatchUri |
Required |
String |
Wildcard pattern used to determine if the message is being sent to a user handled by this route. For example, you might use the pattern sip:*@*litwareinc.com. This pattern matches any user who has a SIP address that: Begins with the characters "sip:". Is followed by the user name (the asterisk indicates that this can be any user name). Is followed by the @ sign. Is followed by "litwareinc.com". Thus the address sip:kenmyer@litwareinc.com would match the pattern, and the message would be routed along this route. The address sip:kenmyer@fabrikam.com would not match the pattern and would not be handled by this route. |
|
MatchOnlyPhoneUri |
Optional |
Boolean |
If set to True, only messages addressed to phone URIs (for example, sip:kenmmyer@litwareinc.com;user=phone) will be matched and, potentially routed. If set to False (the default value) then all messages will be matched. |
|
ReplaceHostInRequestUri |
Optional |
Boolean |
If set to True ($True) then the host portion of a Request-URI will be replaced by the address of the next hop server. If set the False then the Request-URI will be used as-is. The Request-URI represents the URI of the user or service that the request (message) is addressed to. The default value is False. |
|
UseDefaultCertificate |
Optional |
Boolean |
Configures the route to use your default Communications Server certificate as its authentication certificate. If you do not want to use the default certificate then you must specify a different certificate using the –TLSCertIssuer and –TLSCertSerialNumber parameters. To view the default certificate, use the following command: Get-CsCertificate | Where-Object {$_.Use –eq "urn:certref:Default"} |
|
TLSCertIssuer |
Optional |
String |
Name of the Certificate Authority that issued the certificate to be used in the static route. This parameter is not used if you have configured TCP as the transport protocol. |
|
TLSCertSerialNumber |
Optional |
Byte array |
Serial number of the TLS certificate to be used in the static route. Serial numbers must be passed as a byte array; this means you must pass the serial number as an array of two-character values. For example: -TLSCertSerialNumber 01, 23, 45, 67, 89. This parameter is not used if you have configured TCP as the transport protocol. |
Detailed Description
When you send a SIP (Session Initiation Protocol) message to someone that message might need to traverse multiple subnets and networks before it is delivered; the path traveled by the message is often referred to as a route. In networking, there are two types of routes: dynamic and static. With dynamic routing, servers use algorithms to determine the next location (the next hop) where that message should be forwarded. With static routing, message paths are predetermined by system administrators. When a message is received by a server, the server checks the message address and then forwards the message to the next hop server that has been preconfigured by an administrator. If configured correctly, static routes help ensure timely, and accurate, delivery of messages, and with minimal overheard placed on servers. The downside to static routes? Messages are not dynamically rerouted in the event of a network failure.
New static routes are created using the New-CsStaticRoute cmdlet. New routes can also be created by using the New-CsSipProxyRoute cmdlet. However, New-CsSipProxyRoute requires the use of multiple cmdlets and multiple objects in order to create route. Because of that, you will likely find that New-CsStaticRoute is much faster and much easier to use. After a route has been created using New-CsStaticRoute, you must then add the route to a collection of routing configuration settings using the Set-CsStaticRoutingConfiguration cmdlet.
Return Types
New-CsStaticRoute creates new instances of the Microsoft.Rtc.Management.WriteableConfig.Settings.SipProxy.Route object.
Examples
-------------------------- Example 1 ------------------------
 Copy Code |
|
|---|---|
$x = New-CsStaticRoute -TCPRoute -Destination "192.168.0.100" -Port 8025 -MatchUri "sip:*@litwareinc.com"
Set-CsStaticRoutingConfiguration -Identity global -Route @{Add=$x}
|
|
The commands shown in Example 1 create a new static route and then adds that route to the global static routing configuration collection. To carry out this task, the first command uses New-CsStaticRoute to create an in-memory-only route that uses TCP as its transport protocol. The route points to the next hop IP address 192.168.0.100, uses port 8025, and matches any URI that uses the pattern sip:*@litwareinc.com. The resulting route object is stored in a variable named $x.
The second command in the example is then used to add the new route to the global static routing configuration collection. This is done by calling Set-CsStaticRoutingConfiguration along with the –Route parameter. The parameter value @{Add=$x} simply adds the route object stored in $x to the existing set of routes already in the global collection.
-------------------------- Example 2 ------------------------
| Copy Code |
|
|---|---|
$x = New-CsStaticRoute -TLSRoute -Destination "atl-proxy-001.litwareinc.com" -Port 8025 -MatchUri "sip:*@litwareinc.com" -UseDefaultCert $True
Set-CsStaticRoutingConfiguration -Identity global -Route @{Add=$x}
|
|
Example 2 shows how you can create a new static route that uses TLS as its transport protocol, then adds that route to the global static routing configuration collection. To do this, the first command in the example uses New-CsStaticRoute to create an in-memory-only route that uses TLS as its transport protocol. The route points to the next hop IP address 192.168.0.100, uses port 8025, and matches any URI that uses the following pattern sip:*@litwareinc.com. In addition, the new route object, which is stored in a variable named $x, uses the default certificate for authentication purposes (-UseDefaultCert $True).
After the route object has been created, the second command in the example is then used to add the new route to the global static routing configuration collection.