README

   1 A VPN client compatible with Cisco's EasyVPN equipment.
   2
   3 Supports IPSec (ESP) with Mode Configuration and Xauth.  Supports only
   4 shared-secret IPSec authentication with Xauth,
   5 AES (256, 192, 128), 3DES, 1DES, MD5, SHA1,
   6 DH1/2/5 and IP tunneling.
   7
   8 It runs entirely in userspace. Only "Universal TUN/TAP device
   9 driver support" is needed in kernel.
  10
  11 Project home page: http://www.unix-ag.uni-kl.de/~massar/vpnc/
  12
  13
  14 ========= Contents of this file ============================================
  15
  16
  17 - General configuration of vpnc
  18 - Using a modified script
  19 - Additional steps to configure hybrid authentication
  20 - Setting up vpnc on Vista 64bit
  21 - Known problems
  22
  23
  24 ========= General configuration of vpnc ====================================
  25
  26
  27 Required Libraries: libgcrypt (version 1.1.90 for 0.2-rm+zomb-pre7 or later)
  28                     libopenssl (optional, to provide hybrid support)
  29
  30 It reads configuration data from the following places:
  31
  32 - From command-line options
  33 - From config file(s) specified on the command line
  34 - From /etc/vpnc/default.conf  only if no configfile was given on the command line
  35 - From /etc/vpnc.conf          same as default.conf, ie: both are used, or none
  36 - If a setting is not given in any of those places, it prompts the user.
  37
  38 The configuration information it currently needs is:
  39
  40           Option Config file item
  41        --gateway IPSec gateway
  42             --id IPSec ID
  43      (no option) IPSec secret
  44       --username Xauth username
  45      (no option) Xauth password
  46
  47 A sample configuration file is:
  48
  49 # This is a sample configuration file.
  50 IPSec gateway 127.0.0.1
  51 IPSec ID laughing-vpn
  52 IPSec secret hahaha
  53 Xauth username geoffk
  54
  55 Note that all strings start exactly one space after the keyword
  56 string, and run to the end of the line.  This lets you put any kind of
  57 weird character (except CR, LF and NUL) in your strings, but it does mean
  58 you can't add comments after a string, or spaces before them.
  59
  60 It may be easier to use the --print-config option to generate the
  61 config file, and then delete any lines (like a password) that you want
  62 to be prompted for.
  63
  64 If you don't know the Group ID and Secret string, ask your
  65 administrator. If (s)he declines and refers to the
  66 configuration files provided for the vpnclient program, tell
  67 him/her that the contents of that files is (though scrambled)
  68 not really protected. If you have a working configuration file
  69 (.pcf file) for the Cisco client then you can use the pcf2vpnc
  70 utility instead, which will extract most/all of the required
  71 information and convert it into a vpnc configuration file.
  72
  73
  74 ========= Using a modified script ==========================================
  75
  76
  77 Please note that vpnc itself does NOT setup routing. You need to do this
  78 yourself, or use --script "Script" in the config file.
  79 The default script is /etc/vpnc/vpnc-script which sets a default route
  80 to the remote network, or if the Concentrator provided split-network
  81 settings, these are used to setup routes.
  82
  83 This option is passed to system(), so you can use any shell-specials you
  84 like. This script gets called three times:
  85 $reason == pre-init: this is before vpnc opens the tun device
  86    so you can do what is necessary to ensure that it is available.
  87    Note that none of the variables mentioned below is available
  88 $reason == connect: this is what used to be "Config Script".
  89    The connection is established, but vpnc will not begin forwarding
  90    packets until the script finishes.
  91 $reason == disconnect: This is called just after vpnc received a signal.
  92    Note that vpnc will not forward packets anymore while the script is
  93    running or thereafter.
  94
  95 Information is passed from vpnc via environment variables:
  96
  97 #* reason                       -- why this script was called, one of: pre-init connect disconnect
  98 #* VPNGATEWAY                   -- vpn gateway address (always present)
  99 #* TUNDEV                       -- tunnel device (always present)
 100 #* INTERNAL_IP4_ADDRESS         -- address (always present)
 101 #* INTERNAL_IP4_NETMASK         -- netmask (often unset)
 102 #* INTERNAL_IP4_DNS             -- list of dns servers
 103 #* INTERNAL_IP4_NBNS            -- list of wins servers
 104 #* CISCO_DEF_DOMAIN             -- default domain name
 105 #* CISCO_BANNER                 -- banner from server
 106 #* CISCO_SPLIT_INC              -- number of networks in split-network-list
 107 #* CISCO_SPLIT_INC_%d_ADDR      -- network address
 108 #* CISCO_SPLIT_INC_%d_MASK      -- subnet mask (for example: 255.255.255.0)
 109 #* CISCO_SPLIT_INC_%d_MASKLEN   -- subnet masklen (for example: 24)
 110 #* CISCO_SPLIT_INC_%d_PROTOCOL  -- protocol (often just 0)
 111 #* CISCO_SPLIT_INC_%d_SPORT     -- source port (often just 0)
 112 #* CISCO_SPLIT_INC_%d_DPORT     -- destination port (often just 0)
 113
 114 Currently vpnc-script is not directly configurable from configfiles.
 115 However, a workaround is to use a "wrapper-script" like this, to
 116 disable /etc/resolv.conf rewriting and setup a custom split-routing:
 117
 118 ------------------------------
 119 #!/bin/sh
 120
 121 # this effectively disables changes to /etc/resolv.conf
 122 INTERNAL_IP4_DNS=
 123
 124 # This sets up split networking regardless
 125 # of the concentrators specifications.
 126 # You can add as many routes as you want,
 127 # but you must set the counter $CISCO_SPLIT_INC
 128 # accordingly
 129 CISCO_SPLIT_INC=1
 130 CISCO_SPLIT_INC_0_ADDR=131.246.89.7
 131 CISCO_SPLIT_INC_0_MASK=255.255.255.255
 132 CISCO_SPLIT_INC_0_MASKLEN=32
 133 CISCO_SPLIT_INC_0_PROTOCOL=0
 134 CISCO_SPLIT_INC_0_SPORT=0
 135 CISCO_SPLIT_INC_0_DPORT=0
 136
 137 . /etc/vpnc/vpnc-script
 138 ------------------------------
 139
 140 Store this example script, for example in /etc/vpnc/custom-script,
 141 do a "chmod +x /etc/vpnc/custom-script" and add
 142 "Script /etc/vpnc/custom-script" to your configuration.
 143
 144
 145 ========= Additional steps to configure hybrid authentication ==============
 146
 147
 148 To use the hybrid extension add
 149         Use Hybrid Auth
 150 to your .conf file or add
 151         --hybrid
 152 when starting vpnc.
 153
 154 The trusted root certificate may be passed by adding
 155         CA-File <root_certificate.pem>
 156 to your .conf file or adding
 157         --ca-file <root_certificate.pem>
 158 when starting vpnc.
 159
 160 The trusted root certificate may be contained in a directory by adding
 161         CA-Dir <trusted_certificate_directory>
 162 to your .conf file or adding
 163         --ca-dir <trusted_certificate_directory>
 164 when starting vpnc.
 165 The default is
 166         /etc/ssl
 167
 168 As the trusted certificate is referenced by the hash of the subject name,
 169 the directory has to contain the certificate named like this hash_value.
 170 A link can also be used like in /etc/ssl/certs/.
 171 The hash value can be calculated by e.g.
 172         openssl x509 -in <ca_certfile.pem> -noout -hash
 173
 174
 175 ========= Setting up vpnc on Vista 64bit ===================================
 176
 177
 178 1. Install cygwin onto vista.  Details here: http://www.cygwin.com/
 179 2. Make sure you install the development options for cygwin to give you
 180    access to make and gcc etc
 181 3. Make sure you install libgcrypt for cygwin as it is needed in the make
 182 4. Modify the bash.exe to run as administrator or you will have
 183    privilege issues later, this is done on the properties tab of the
 184    executable in c:/cygwin/bin
 185 4. Download the latest vpnc tarball from here
 186    http://www.unix-ag.uni-kl.de/~massar/vpnc/
 187 5. Unzip and explode the tarball
 188 6. modify tap-win32.h to change #define TAP_COMPONENT_ID "tap0801" to
 189    "tap0901" (No sure if this is necessary but I did it and it is working
 190    for me)
 191 7. make
 192 8. You should have a shinny new vpnc.exe
 193 9. Download openvpn from http://openvpn.net/download.html.  I used
 194    openvpn-2.1_rc4-install.exe as all other version I tried had errors
 195    during install
 196 10. Run the exe but only install the TAP-Win32 Adapter V9
 197 11. Go to control Panel | Network Connections and rename the TAP device
 198     to my-tap
 199 12. create a /etc/vpnc/default.conf file something like this
 200 ------------- begin -------------
 201 IPSec gateway YOURGATEWAY
 202 IPSec ID YOURID
 203 IPSec obfuscated secret YOURREALYLONGHEXVALUE (you can use your clear
 204 text password here if you remove obfuscated)
 205 Xauth username YOURUSERNAME
 206 Xauth password YOURPASSWORD
 207 Interface name my-tap
 208 Interface mode tap
 209 Local Port 0
 210 ------------- end ---------------
 211     See the general config section above and the manpage for details.
 212
 213
 214 ========= Known problems ===================================================
 215
 216
 217 Known problems:
 218
 219 Problem:
 220 In some environments it may happen that stuff works for a while and then
 221 stops working.
 222
 223 Reason:
 224 The dhcp leases are very short intervals and on each renew the dhcp
 225 client overwrites things like /etc/resolv.conf and maybe the default route.
 226
 227 Solution:
 228 Fix your dhcpclient. On Debian that problem can be fixed by installing
 229 and using resolvconf to modify that file instead of modifying it directly.
 230
 231
 232 ============================================================================
 233