stonesoft ipsec vpn client

Stonesoft IPsec VPN Client 5.4.1

Automated Mode for IPsec VPN Client

How-To

CONTENTS

Introduction to Using IPsec VPN Client in Automated Mode ... 2

Preparing for Installation .................................................... 2

Saving the Gateway Contact Information File ....................... 3

Installing the IPsec VPN Client ........................................... 5

Adjusting the Connection Retry Times ................................. 10

Error Handling in Automated Mode ..................................... 11

Other Differences from the Standard Mode ......................... 12

1

Introduction to Using IPsec VPN Client in Automated Mode

This document describes how you can configure Stonesoft IPsec VPN Client 5.4.1 to establish and maintain VPN connections automatically. If the IPsec VPN Client is started in automated mode, it automatically creates a VPN connection to the VPN gateway specified in the IPsec VPN Client's configuration. It also automatically creates a VPN when the machine on which the IPsec VPN Client has been installed is started.

The IPsec VPN Client user is authenticated either with a certificate or with a password. The first certificate found in the IPsec VPN Client's Certificate's directory is used with certificate authentication.

If you want to use the IPsec VPN Client in automated mode on a machine on which the IPsec VPN Client is already installed, uninstall the IPsec VPN Client and then reinstall it according to the instructions in this document. You cannot make an existing IPsec VPN Client installation run in automated mode.

Preparing for Installation

The following files are always needed for installing the IPsec VPN Client for use in automated mode:

• IPsec VPN Client installation file• gateway contact information file for the IPsec VPN Client

Depending on the authentication method, one of the following is also needed:

• If a password is used, you must have the password file for the IPsec VPN Client.• If a certificate is used, you must have a private key file and a certificate file for the IPsec VPN

Client.

If the IPsec VPN Client user is authenticated with a password, you must create a .txt file which defines the password and the username and optionally the signature type that matches the gateway's certificate (RSA, DSS, or ECDSA). If the signature type is not specified in the password file, RSA is used.

The username and the password are defined in the following format in the password file:

<user>username</user>

<pass>password</pass>

The signature type is defined in one of the following ways:

<auth>RSA</auth>

<auth>DSS</auth>

<auth>ECDSA</auth>

The private key file and certificate file or the password file are used to authenticate the user. Only one of the authentication methods can be used at the same time. The gateway contact information file contains the information the IPsec VPN Client needs for making an initial connection to a gateway. The installer asks for the gateway contact information file and for the

Note – The private key must not be encrypted.

2 Contents

files used in authentication (the private key file and certificate file, or the password file) during the installation. The gateway contact information file is created in the Stonesoft Management Center.

Configuration OverviewThere are two main steps in installing the IPsec VPN Client in automated mode:

1. Save the gateway contact information file in the Stonesoft Management Client.

2. Install the IPsec VPN Client.

Saving the Gateway Contact Information File

The following instructions explain how to save the gateway contact information file in Stonesoft Management Center 5.4. If you are using another Management Center version, refer to the Management Client Online Help or the Stonesoft Administrator's Guide for instructions.

To save the gateway contact information file in the Management Client1. Open the Management Client.

2. Select Configuration→Configuration→VPN. The VPN Configuration view opens.

3. Browse to VPN→Gateways.

What’s Next? Saving the Gateway Contact Information File

3

3Saving the Gateway Contact Information File

4. Right-click the gateway to which the IPsec VPN Client connects and select Tools→SaveGateway Contact Information. A file save dialog opens.

5. Select the location where you want to save the file and click Save.

What’s Next? Installing the IPsec VPN Client (page 5)

4

4 Contents

Installing the IPsec VPN Client

You can install the IPsec VPN Client either interactively with an installation wizard or silently with a command line script.

Proceed to one of the following:

• Installing the IPsec VPN Client in Interactive Mode• Installing the IPsec VPN Client in Silent Mode (page 7)

Installing the IPsec VPN Client in Interactive Mode

To install the IPsec VPN Client in interactive mode1. Open the command prompt.

2. Run the installation file with one of the following parameters: • If you use the .exe installation file, use /VSG_INSTALL_MODE="Auto" as the parameter.• If you use the .msi installation file, use SG_INSTALL_MODE="Auto" as the parameter.

3. Select the gateway contact information file as prompted by the installation wizard.

5Installing the IPsec VPN Client

4. Select either the private key file and the certificate file, or the password file, as promptedby the installation wizard. See the illustrations below.

Illustration 1.1 Selecting the Private Key and Certificate Files

Illustration 1.2 Selecting the Password File

When the installation is finished, IPsec VPN Client has been configured for use in automated mode. It will start automatically and try to establish a VPN to the gateway.

If the number of IPsec VPN Clients is large, it may be necessary to adjust the default connection retry times. See Adjusting the Connection Retry Times (page 10).

For more information on how the IPsec VPN Client functions in automated mode, see Error Handling in Automated Mode (page 11) and Other Differences from the Standard Mode (page 12).

6 Contents

Installing the IPsec VPN Client in Silent ModeAs an alternative to interactive installation, you can use a script for installing the IPsec VPN Client in silent mode. You can either create your own script or use one of the example scripts (script 1 or 2) below.

Illustration 1.3 Example Script 1

@echo.

@echo * Installing Stonesoft IPsec VPN Client. If .NET2.0 Framework needs to be installed this may take some time...

%1 /s /v"/qn /L*v install_log.txt SG_INSTALL_MODE=Auto"

@echo.

@echo * Stopping Stonesoft IPsec VPN Client Service...

net stop sgipsecvpn

@echo.

@echo * Copying configuration files...

copy %2 "%ALLUSERSPROFILE%\Application Data\Stonesoft\Stonesoft IPsec VPN Client\certificates\client.crt"

copy %3 "%ALLUSERSPROFILE%\Application Data\Stonesoft\Stonesoft IPsec VPN Client\certificates\client.prv"

copy %4 "%ALLUSERSPROFILE%\Application Data\Stonesoft\Stonesoft IPsec VPN Client\gateway_info\contact_info_a.xml"

@echo.

@echo * Starting Stonesoft IPsec VPN Client Service...

net start sgipsecvpn


Illustration 1.4 Example Script 2

Each example script does the following:

It starts the installer with the following arguments: /s /v"/qn /L*v install_log.txt SG_INSTALL_MODE=Auto". It also creates a log file install_log.txt from the installation process.

It then starts the IPsec VPN Client. The IPsec VPN Client service is still shut down because the files used in authentication (the private key file and certificate file, or the password file) and the gateway contact information file are still missing.

Next the script copies the missing files to the directory %ALLUSERSPROFILE%\Application Data\Stonesoft\Stonesoft IPsec VPN Client.

Finally, the script starts the IPsec VPN Client service.

@echo.

@echo * Installing Stonesoft IPsec VPN Client. If .NET2.0 Framework needs to be installed this may take some time...

%1 /s /v"/qn /L*v install_log.txt SG_INSTALL_MODE=Auto"

@echo.

@echo * Stopping Stonesoft IPsec VPN Client Service...

net stop sgipsecvpn

@echo.

@echo * Copying configuration files...

copy %2 "%ALLUSERSPROFILE%\Application Data\Stonesoft\Stonesoft IPsec VPN Client\passwd.txt"

copy %3 "%ALLUSERSPROFILE%\Application Data\Stonesoft\Stonesoft IPsec VPN Client\gateway_info\contact_info_a.xml"

@echo.

@echo * Starting Stonesoft IPsec VPN Client Service...

net start sgipsecvpn

8 Contents

To use the script, put all the relevant files in the same directory:

• script file• IPsec VPN Client installation file• gateway contact information file for the IPsec VPN Client• (If a certificate is used as the authentication method) certificate file and private key file for the

IPsec VPN Client• (If a password is used as the authentication method) password file for the IPsec VPN Client

To install the IPsec VPN Client silently1. Open a command prompt as an administrator.

2. Run the script and enter the parameters according to the selected authentication method:• If you use a certificate (Example Script 1), enter: script.bat <INSTALLER.EXE> <CERTIFICATE> <PRIVATE_KEY> <GW_CONTACT_INFO_FILE>

• If you use a password (Example Script 2), enter: script.bat <INSTALLER.EXE> <PASSWORD> <GW_CONTACT_INFO_FILE>

See examples of the two alternative authentication methods below. The first one is an example of using a certificate file and a private key file and the second is an example of using a password file as the authentication method.

Example Using a certificate with the script:C:\install>script.bat Stonesoft_IPsec_VPN_5.4.1.2407_with_NET2.0.exe certificate.crt certificate.prv Security GW_info_20130304_122304.xml

Example Using a password with the script:C:\install>script.bat Stonesoft_IPsec_VPN_5.4.1.2407_with_NET2.0.exe password.txt Security GW_info_20130304_122304.xml

When the installation is finished, IPsec VPN Client has been configured for use in automated mode. It will start automatically and try to establish a VPN to the gateway.


For more information on how the IPsec VPN Client functions in automated mode, see Error Handling in Automated Mode (page 11) and Other Differences from the Standard Mode (page 12).

Note – If you use your own script for the installation, use the same destination file names for the certificate and the private key as in the example script (client.crt and client.prv).


Adjusting the Connection Retry Times

The default connection retry times for automated IPsec VPN Client are:

• minimum connection retry time: 3 seconds• maximum connection retry time: 192 seconds.

In installations that have a large number of automated IPsec VPN Clients, it may be necessary to adjust the default connection retry times (for example, to ensure connectivity after network outages). To adjust the default connection retry times, modify the retryconf.txt file and save it to the directory ALLUSERSPROFILES\Application Data\Stonesoft\Stonesoft IPsec VPN Client\retryconf.txt. The IPsec VPN Client must be installed before you can save the retryconf.txt file to the directory.

The syntax for adjusting the connection retry times using the retryconf.txt file is the following:

<min>minimum connection retry time in seconds</min>

<max>maximum connection retry time in seconds</max>

<rnd>percentage of randomness in connection retry time</rnd>

The default connection retry time is an increasing multiple of the minimum connection retry time, but it does not exceed the maximum connection retry value. The randomness percentage adds time*rnd(-1.0 .. 1.0)*percentage/100 to the connection retry time during each attempt. However, the connection retry time never exceeds the maximum connection retry time or goes below the minimum connection retry time.

Unless specified in the configuration file, the randomness percentage is not used. If the retryconf.txt file does not exist in the directory, the default connection retry times are used.

10 Contents

Error Handling in Automated Mode

If errors occur in VPN connections, the IPsec VPN Client tries to recover from them automatically. There are two types of errors: unrecoverable and recoverable.

Unrecoverable ErrorsUnrecoverable errors cannot be resolved automatically and require user interaction. If the IPsec VPN Client encounters an unrecoverable error, it shuts itself down and does not try to restart itself. The unrecoverable errors are:

• A required certificate, private key, or gateway information file is missing or contains invalid information.

• The private key is encrypted and requires entering a passphrase.• The password file is incorrectly formatted or contains incorrect information (for example,

there is a typo in the username or password).

Recoverable ErrorsRecoverable errors do not require user interaction. When the IPsec VPN Client encounters a recoverable error, it automatically tries to establish a new VPN connection to the gateway. Depending on the error, the next connection attempt is either a normal connection to the next gateway end-point or an initial connection.

The IPsec VPN Client tries to make a normal connection when the following errors occur:

• Any connection state fails due to a recoverable error.• Gateway connectivity problems have been detected (dead peer detection).

The IPsec VPN Client tries to make an initial connection when the following errors are encountered:

• Configuration load fails. This can happen if the IPsec VPN Client receives an invalid configuration file from the gateway.

• The IPsec VPN Client has already tried to connect to all gateway end-points to solve the error.

When an error that does not require an initial connection occurs, the IPsec VPN Client always tries to connect to the next gateway end-point. When an initial connection is required, the IPsec VPN Client starts the connection attempts from the first gateway end-point specified in the gateway information file. If an initial connection fails before the IPsec VPN Client has retrieved the configuration file from the gateway (and thus requires another initial connection), the IPsec VPN Client tries to connect to the next gateway end-point.

If an initial connection is required to recover from an error, the IPsec VPN Client usually waits for 3 seconds before initiating the connection. If the initial connection fails before a VPN connection has been established successfully, the delay before the next connection attempt increases exponentially (3 s, 6 s, 12 s, etc.) up to a maximum of one hour.


11Error Handling in Automated Mode

Other Differences from the Standard Mode

The IPsec VPN Client user interface is not started automatically when the IPsec VPN Client has been installed in automated mode. If necessary, you can start the user interface from the Programs folder in the Start menu. In automated mode, the user interface can only be used for monitoring the connection status. All commands from the user interface are ignored.

12 Contents

Stonesoft Guides

Administrator’s Guides - step-by-step instructions for configuring and managing the system.

Installation Guides - step-by-step instructions for installing and upgrading the system.

Reference Guides - system and feature descriptions with overviews to configuration tasks.

User's Guides - step-by-step instructions for end-users.

For more documentation, visit

www.stonesoft.com/support/

Stonesoft Corporation

Itälahdenkatu 22 AFI-00210 Helsinki

Finland

Tel. +358 9 476 711Fax +358 9 4767 1349

Stonesoft Inc.

1050 Crown Pointe ParkwaySuite 900Atlanta, GA 30338USA

Tel. +1 770 668 1125Fax +1 770 668 1131

Copyright 2013 Stonesoft Corporation. All rights reserved. All specifications are subject to change.

http://www.stonesoft.com/en/support/

stonesoft ipsec vpn client

Documents