The Sample PowerShell Script and Data File

  • Article

Applies To: Windows 7, Windows Server 2003, Windows Server 2003 R2, Windows Server 2008, Windows Server 2008 R2, Windows Vista

The version of this guide that is hosted on the Microsoft Download Center (https://go.microsoft.com/fwlink/?linkid=160558) includes a sample PowerShell script and XML data file. The script reads the XML file as input, and uses it to specify how the VPN connection is to be configured. You only need to modify the XML file to add new VPN connections or change existing VPN connections on your client computers.

Disclaimer

The sample script and data file described in this guide are not supported under any Microsoft standard support program or service. The sample script and data file are provided AS IS without warranty of any kind. Microsoft further disclaims all implied warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The entire risk arising out of the use or performance of the sample scripts and documentation remains with you. In no event shall Microsoft, its authors, or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the sample scripts or documentation, even if Microsoft has been advised of the possibility of such damages.

Warning

Test the script and its accompanying data file thoroughly in a test environment, and customize it to meet the requirements of your organization before attempting to use it in a production capacity.

This topic describes the structure of the XML data file as required by the sample PowerShell script. If you modify the script, you might have to modify the structure of the data file to match your changes.

The sample script uses the publicly documented RAS APIs and data structures to create or modify VPN connection settings. The C# code embedded in the script parses the input XML data file and loads them as settings for a VPN connection. The script then constructs a RASENTRY (https://go.microsoft.com/fwlink/?linkid=160268) data structure, translates it into Win32 form, and then calls the RasSetEntryProperties (https://go.microsoft.com/fwlink/?linkid=160272) function to create the VPN connection from the data in the RASENTRY structure.

The XML data file contains the following elements:

  • An XML header

  • An XML root element named RemoteAccessEntries. This contains one or more child elements named RemoteAccessEntry.

  • Each RemoteAccessEntry element corresponds to a single VPN connection profile, and contains child elements that specify the settings for the connection.

The following table describes each of the elements supported in the XML data file. The settings for an individual VPN connection are mostly optional; if not present, the PowerShell script uses a default value.

Note

Element name

  • True – Shared by everyone on client computer

  • False – Available only for the currently logged on user on the client computer

Default: True

ConnectionType

Specifies the type of connection to the remote network.

  • Dialup – Dial-up networking connection

  • VPN – Virtual private network connection

  • Direct – Direct connection

  • Internet – Custom dialer

  • Broadband – PPPoE connection

Default: VPN

Negotiate_IPv4

Specifies whether IPv4 must be negotiated between the VPN client and VPN server.

  • True – Negotiate IPv4

  • False – Do not negotiate IPv4

Default: True

Negotiate_IPv6

Note

This option does not apply to computers that are running Windows XP or Windows Server 2003.

Specifies whether IPv6 must be negotiated between the VPN client and VPN server.

  • True – Negotiate IPv6

  • False – Do not negotiate IPv6

Default: True

VpnStrategy

Specifies the order in which the VPN tunnels types are tried.

  • PPTPOnly – Try only Point-to-Point Tunneling Protocol (PPTP)

  • L2TPOnly – Try only Layer Two Tunneling Protocol (L2TP)

  • SSTPOnly – Try only Secure Socket Tunneling Protocol (SSTP)

  • IKEv2Only – Try only Internet Key Exchange version 2 (IKEv2)

  • PPTPWithSSTP – Try PPTP, and if fails, try SSTP

  • L2TPWithSSTP – Try L2TP, and if fails, try SSTP

  • IKEv2WithSSTP – Try IKEv2, and if fails, try SSTP

Default: IKEv2withSSTP

RouteIPv4TrafficOverRAS

Specifies whether the VPN connection becomes the IPv4 default gateway on the client computer for the duration of the connection.

  • True – Add a default gateway on the VPN connection

  • False – Do not add default gateway on the VPN connection

Default: True

RouteIPv6TrafficOverRAS

Specifies whether the VPN connection becomes the IPv6 default gateway on the client computer for the duration of the connection.

  • True – Add a default gateway on the VPN connection

  • False – Do not add a default gateway on the VPN connection

Default: True

ShowUsernamePassword

Specifies Specifies whether to show the Username and Password fields in the remote access connection manager interface.

  • True – Show the Username and Password fields

  • False – Hide the Username and Password fields

Default: True

ShowDomain

Specifies whether to show the Domain field in the remote access connection manager interface.

  • True – Show the Domain field

  • False – Hide the Domain field

Default: True

ShowDialProgressBar

Specifies whether to show the connection progress during the establishment of the connection.

  • True – Show the connection progress

  • False – Hide the connection progress

Default: True

RequireCHAP

Specifies whether CHAP authentication is required for the VPN connection.

Security Note
We recommend that you do not use CHAP authentication.

  • True – Negotiate CHAP

  • False – Do not negotiate CHAP

Default: True

RequireMSCHAPv2

Specifies whether Microsoft Challenge Handshake Authentication Protocol version 2 (MS CHAP v2) authentication is required for the VPN connection.

Security Note
We recommend that you consider EAP instead of MS CHAP v2 because EAP is not dependent on passwords.

  • True – Negotiate MS CHAP v2

  • False – Do not negotiate MS CHAP v2

Default: True

RequireEAP

Specifies whether EAP authentication is required for the VPN connection.

Security Note
We recommend the use of EAP authentication over CHAP, MS CHAP v1, or MS CHAP v2.

  • True – Negotiate EAP

  • False – Do not negotiate EAP

Default: False

RequireEncryptedPassword

Specifies whether the VPN connection requires either CHAP, MS CHAP v1, or MS CHAP v2 authentication.

Security Note
We recommend the use of EAP authentication over CHAP, MS CHAP v1, or MS CHAP v2.

  • True – Require the use of CHAP, MS CHAP v1, or MS CHAP v2 authentication

  • False – Do not require the use of CHAP, MS CHAP v1, or MS CHAP v2 authentication

Default: True

RequireMsEncryptedPassword

Specifies whether the VPN connection requires MS CHAP v1 or MS CHAP v2 authentication.

Security Note
We recommend the use of EAP authentication over MS CHAP v1 or MS CHAP v2.

  • True – Require the use of MS CHAP v1 or MS CHAP v2 authentication

  • False – Do not require MS CHAP v1 or MS CHAP v2 authentication

Default: True

DontCacheRASCredentialsInCredman

Specifies whether user credentials used by the VPN connection are stored in Windows Credential Manager. The user does not have to enter additional credentials for subsequent resource access if the VPN credentials are valid for access.

Credentials are stored on a per user basis. Credentials cached by one user cannot be used by another user.

  • True – Do not cache user credentials

  • False – Cache user credentials

Default: False

ReconnectIfDropped

Specifies whether the VPN connection should be reestablished if it is unexpectedly disconnected.

  • True – Reconnect if VPN connection drops

  • False – Do not reconnect if VPN connection drops

Default: True

ProxySettings

Specifies the proxy settings for the current VPN connection. It has child elements each specifying a part of configuration for Internet Explorer.

No values; contains only child elements.

UseManualProxy (child element of ProxySettings)

Specifies whether the proxy setting in Internet Explorer is configured by this connection profile.

  • True – Use manual proxy specified in the ManualProxyServer element

  • False – Do not change the proxy setting in Internet Explorer

Default: False

UseAutoProxy (child element of ProxySettings)

Specifies whether the proxy setting is configured automatically.

  • True – Use automatic proxy detection

  • False – Do not use automatic proxy detection

Default: False

UseAutoConfigurationScript (child element of ProxySettings)

Specifies whether to use a proxy auto-configuration script.

  • True – Use proxy auto-configuration script

  • False – Do not use proxy auto-configuration script

Default: False

ManualProxyServer (child element of ProxySettings)

Specifies the manual proxy server name for the VPN connection in Internet Explorer.

A text string that identifies the fully qualified domain name (FQDN) or IP address of the proxy server to use.

ProxyOverride (child element of ProxySettings)

Specifies Domain Name System (DNS) names or addresses for which the proxy should not be used.

A comma-separated list of resolvable DNS names or IP addresses.

ByPassProxyForLocal (child element of ProxySettings)

Specifies whether the proxy server is bypassed for local subnet addresses.

  • True – Bypass proxy for local subnet addresses

  • False – Do not bypass the proxy server for local subnet addresses

AutoConfigurationScript (child element of ProxySettings)

Specifies the Web Proxy Auto Discovery (WPAD) configuration script.

The universal naming convention (UNC) file path to the auto-configuration script.

Destination

Specifies a destination IP address or phone number for the VPN connection. It has one child element, DestinationAddress, which contains the destination information. You can specify one or more Destination elements, each with its own DestinationAddress child element.

No values; contains only child elements.

DestinationAddress (child element of Destination)

Specifies the IP address in case of VPN connections, phone number in case of dial-up connections and service names in case of PPPoE connections.

  • An IPv4 or IPv6 address of a VPN server on the network

  • The phone number of a dial-up server

  • The service name provided by your PPPoE service provider