From Gentoo Wiki
Jump to:navigation Jump to:search
This page contains changes which are not marked for translation.
This page is a work in progress by Needle (talk) 19:39, 3 February 2024 (UTC). Treat its contents with caution.
net-misc/vpnc no longer in Gentoo ebuild repository.

VPNC is a IPsec (Cisco/Juniper) VPN concentrator client to manage secure connections, for users needing to connect to office network from home or during travel. Connecting to a Cisco and Juniper VPN concentrator is possible using Linux, and it should be possible setup a working tunnel using a Gentoo workstation or laptop.

VPNC is a VPN client compatible with Cisco's EasyVPN equipment. It supports IPSec (ESP) with Mode Configuration and Xauth. Supports only shared-secret IPSec authentication with: Xauth, AES (256, 192, 128), 3DES, 1DES, MD5, SHA1, DH1/2/5 and IP tunneling. VPNC runs entirely in userspace. Only universal TUN/TAP device driver support is needed in kernel.

About this guide

What this document is

  • A guide to the basic workings of vpnc
  • A discussion of DNS and routing issues that relate to VPNs
  • Examples of managing VPN sessions
  • Useful tips and tricks (hopefully)

What this document is not

  • An in-depth guide to VPN/encryption technologies
  • A feature by feature explanation of vpnc


The assumptions made at this point are:

  • Gentoo is installed
  • Internet access is available and configured
  • The connection is towards a Cisco 3000 VPN concentrator - vendor EOL announcement 2012
  • The conneciton is towards a Cisco Firewall or more generic vendor specific IPsec concentrator
  • Configuring, building, and installing a new kernel is not a daunting task for the reader



In order for Linux to be able to open a VPN connection Universal TUN/TAP device driver support must be enabled in the kernel. What is it and why is it needed? Below is a relatively straight forward explanation from the kernel configuration dialog:

To verify that the kernel has TUN/TAP support, grep the kernel's configuration file:

root #grep TUN= /usr/src/linux/.config

As can be seen above, CONFIG_TUN=m is compiled as a module. If it is disabled in the setup, enable it in the kernel of choice, rebuild, install, reboot and return to this document before continuing with the next steps.

KERNEL Configuration location in the kernel configuration dialog
Device Drivers  --->
    [*] Network device support  --->
        [*] Network core driver support
        <*>   Universal TUN/TAP device driver support

If TUN/TAP support is built directly into the kernel, dmesg output should look like the following:

root #dmesg | grep TUN
[    1.027934] tun: Universal TUN/TAP device driver, 1.6


Now that a working kernel setup is completed, install the net-misc/vpnc package:

root #emerge --ask net-misc/vpnc


In order to make the following sections more clear, we need an example setup to work from. For the purpose of this exercise, we will assume that the home network consists out of several computers. All computers are on the / network. The LAN in question is run by a Gentoo box using an iptables firewall, DHCP, caching DNS, etc ... and it masquerades the LAN behind the public IP address it receives from an ISP. A workstation is also on the LAN from which the VPN into the office will be configured.

Our example workstation configuration looks like the following:

FILE /etc/resolv.conf
root #ip add show eth0
2: eth0: <BROADCAST,MULTICAST,UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
    link/ether 0c:b6:51:cd:00:00 brd ff:ff:ff:ff:ff:ff
    inet scope global eth0
       valid_lft forever preferred_lft forever
root #ip route
default via dev eth0 dev eth0 proto kernel scope link src 


Now that vpnc is installed and we have an example to work from, let's discuss the basics of setting up vpnc. The configuration file for vpnc connection settings can be located in a couple places, depending on how many profiles need to be configured. By default, vpnc looks for /etc/vpnc/vpnc.conf for its connection settings. This setup will only address a single profile example and will use the configuration file location /etc/vpnc/vpnc.conf .

FILE /etc/vpnc.conf
IPSec gateway vpngateway.example.net
IPSec ID tunnel-split
IPSec secret gentoo-linux-rocks
Xauth username larry
Xauth password gentoo-linux-rocks-and-I-am-a-cow

The configuration file example above should be modified to reflect the appropriate values for the local setup. The gateway option vpngateway.example.net can be a fully qualified domain name or an IP address. The ID and secret options should be given by a network administrator. If this information cannot be obtained but a working setup on a Windows box is available which utilizes the official Cisco VPN client, then it suffices to export the profile. The user name and password options are for the normal network sign-on, such as a Windows NT domain account.

When the profile is exported from a Windows machine, then the result is most likely a file ending in .pcf . This file will have all the necessary information. Below is an example:

FILE profile.pcf

In the above example, we can see entries for Host, GroupName, and enc_GroupPwd. The Username and UserPassword may or may not be exported depending on the setup. To generate a working vpnc configuration out of it, use pcf2vpnc, included with vpnc.

The password can be decrypted with the help from the cisco-decrypt program, shipped with the latest vpnc.

Converting the ~/profile.pcf file into a /etc/vpnc/vpnc.conf working configuration using the pcf2vpnc tool:

user $pcf2vpnc profile.pcf
## generated by pcf2vpnc
IKE Authmode psk
IKE DH Group dh2
IPSec secret ASD1v5J.a&H.tkfJ

IPSec ID group_id

## To add your username and password,
## use the following lines:
# Xauth username <your username>
# Xauth password <your password>


Now that a configuration is in place it is time to test the setup. To start vpnc do the following:

root #vpnc
Enter password for username@vpngateway.example.net:
VPNC started in background (pid: 14788)...

The above command output shows that, once vpnc (as root) is executed, a prompt comes up asking for a password. After entering the password (which will not be echoed to the terminal), the vpnc process will automatically become a background process.

If the Xauth password option is specified in the vpnc config file, then at vpnc startup no password will be asked. Additionally, if vpnc needs some extra options not specified in the configuration file, or if something is forgotten, don't worry, it will ask for it.
root #ip add
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    inet scope host lo
       valid_lft forever preferred_lft forever
    inet6 ::1/128 scope host proto kernel_lo 
       valid_lft forever preferred_lft forever
2: eth0: <BROADCAST,MULTICAST,UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
    link/ether 0c:b6:51:cd:00:00 brd ff:ff:ff:ff:ff:ff
    inet scope global eth0
       valid_lft forever preferred_lft forever
3: tun0: <POINTOPOINT,MULTICAST,NOARP,UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 500
    inet scope global tun0
       valid_lft forever preferred_lft forever
root #netstat -r
root #This needs a fix, put numeric output here
Kernel IP routing table
Destination     Gateway         Genmask         Flags   MSS Window  irtt Iface       router UGH    1500 0          0 eth0       *        U         0 0          0 eth0
loopback        desktop       UG        0 0          0 lo
default         *              U         0 0          0 tun0

As can be seen from the above command output(s), vpnc has done the following:

  • Created the tun0 network interface, a virtual interface to handle the traffic across the VPN tunnel
  • Obtained the IP address for the tun0 device from the VPN provider
  • Set the default route to the VPN gateway

At this point, the workstation is capable of communicating with hosts via the VPN. Because vpnc sets the default route to the VPN gateway, all network traffic will travel across the VPN, even if it destined for the Internet or elsewhere not specifically specified by additional routes. For some, this basic type of connection may be satisfactory, but for most, additional steps need to be taken.

Additional things that might be interesting to have:

  • DNS for the VPN
  • A routing setup that will only send traffic destined for the VPN down the virtual tunnel. This way, browsing the Internet will originate directly from the local network even when connected to the VPN, without the personal web/p2p etc. traffic going across the tunnel.
  • A script to manage all this, because vpnc just doesn't do enough by default.

To end the VPN session, execute vpnc-disconnect. An example is shown below.

Don't disconnect yet, because we have additional things to test. The example below is just for informational purposes.
root #vpnc-disconnect
Terminating vpnc daemon (pid: 26250)

The routing table

The ideal scenario would be if only the traffic destined for the VPN tunnel would travel across the link. At this point, a VPN tunnel setup exists and all traffic will travel across the tunnel, unless additional routes are specified. In order to fix this situation, know what networks are available on the VPN. The easiest way to find out the needed information is to ask a network administrator, but sometimes they are reluctant to answer such questions. If the local network admin doesn't provide the needed information, some trial and error experiments will be required.

When the VPN tunnel was started, vpnc set the default route to the tunnel. So set the default route back to normal, so that things work as expected.

root #ip route add default via

Earlier, when DNS services were being configured for the VPN, a DNS server was specified to handle the example.org domain. Add a route for the subnet so that DNS queries will work:

root #ip route add dev tun0

At this point, any additional routes for known networks (such as for the subnet, which includes the IP address received by the TUN/TAP virtual device) should be added. If a friendly network administrator gave the required info, great. Otherwise, start pinging hosts that will be connected to frequently, to give an idea about what the routing table should look like.

Due to the setup, when using VPN network services by name, specify the fully qualified domain name, for instance: webserver1.example.org
user $ping intranet1.example.org
PING intranet1.example.org ( 56(84) bytes of data.
--- intranet1.example.org ping statistics ---
18 packets transmitted, 0 received, 100% packet loss, time 16997ms

As seen from the above example, the ping probes to intranet1.example.org were unsuccessful. So we need to add a route for that subnet.

root #ip route add dev tun0

A few ping and route commands later, and the system should be well on its way to a well working routing table.

Manage the connection

Calling vpnc when needed

Next is an example script to manage the VPN connection. Execute it (as root) from an xterm to start a connection to the VPN. Then all that is left to do is to press return to disconnect the VPN. Obviously this needs to be modified on the current setup, remembering to add all the additional routes that may be necessary.

FILE sessionmgmt.shExample session management script
source /sbin/functions.sh
ebegin "Connecting to the VPN"
ebegin "Adding static IP route entries"
ip route add default via
ip route add via dev tun0
ip route add via dev tun0
ip route add via dev tun0
einfo "Press any key to disconnect ..."
read $disconnect
ebegin "Disconnecting from the VPN"
ebegin "Adding default route entry"
ip route add default via
einfo "VPN should now be disconnected"

Start vpnc on boot

Version 0.4.0-r1 of vpnc contains an init script (/etc/init.d/vpnc) which can handle multiple configurations. The default script looks for /etc/vpnc/vpnc.conf, but as many configurations as can be imagined are possible. Before and after shutdown and start-up custom-made scripts can be executed that are connected by their name to the corresponding init script (since version 0.5.1-r1). Their names end in -preup.sh, -postup.sh, -predown.sh and -postdown.sh, stored in the /etc/init.d/scripts.d/ directory. The general naming scheme is sketched in the following table.

Init script name Needed configuration file Pre-up script name
/etc/init.d/vpnc /etc/vpnc/vpnc.conf /etc/vpnc/scripts.d/vpnc-preup.sh
/etc/init.d/vpnc.work /etc/vpnc/work.conf /etc/vpnc/scripts.d/work-preup.sh

Add vpnc to default runlevel with the following commands (in this case for the standard configuration). Do not forget to add the tun module (if built that way) to the kernel's autoload mechanism at startup.

root #rc-update add vpnc default

To not have to save the password in the configuration file, tell the init script to show all output and prompts on standard output by editing /etc/conf.d/vpnc. Set the VPNCOUTPUT variable to yes or no, where its default is to not display screen output.

The init scripts don't handle DNS separation, but can use custom scripts to achieve that.


Configuration debugging

Use the --debug n running option to get more verbose output. Following options are available:

user $vpnc --help
--debug <0/1/2/3/99>
     Show verbose debug messages
      *  0: Do not print debug information.
      *  1: Print minimal debug information.
      *  2: Show statemachine and packet/payload type information.
      *  3: Dump everything exluding authentication data.
      * 99: Dump everything INCLUDING AUTHENTICATION data (e.g. PASSWORDS).
 conf-variable: Debug<0/1/2/3/99>

Example output of configuration debugging --debug 1 a not working connection session:

root #vpnc --debug 1 /etc/vpnc/vpnc.conf

vpnc version 0.5.3
response was invalid [1]:  (ISAKMP_N_INVALID_EXCHANGE_TYPE)(7)

Optionally enable debug output in the /etc/vpnc/vpnc.conf configuration file add follwing line at the last line:

Xauth username larry
debug 2

See also

  • OpenVPN — software that enables the creation of secure point-to-point or site-to-site connections.
  • WireGuard — a modern, simple, and secure VPN that utilizes state-of-the-art cryptography.
  • VPN services

External resources

This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: David H. Askew, Christian Faulhammer, Thomas Fischer, nightmorph
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.