Parent page: Internet and Networking


Needs Updating
This article needs updating to include the latest versions of Ubuntu. More info...

Connecting to a VPN in Ubuntu

This document was originally written for Ubuntu 6.10 (Edgy Eft), running the GNOME desktop, by freeatlast. It describes connecting to a VPN as a client. There is also information available on how to set up a VPN server.


If you are lucky, you will be able to get connected using the instructions in this section. If not, the remainder of this document will walk you through the process in more detail, and hopefully will help you get sorted!

  • Obtain your connection type (currently available are Microsoft PPTP, Cisco, or OpenVPN) and authentication details from your VPN administrator.
  • Install Network Manager Applet through the Add/Remove in the Ubuntu menu.

  • Install the plug-in for your connection type - either network-manager-pptp, network-manager-vpnc (Cisco) or network-manager-openvpn (use Synaptic Package Manager or apt-get).

  • Left click the network manager applet (two monitor screens one behind the other probably in the bottom right of your screen) and select VPN Connections->Configure VPN->Add, then enter your connection details. There may be another icon that looks similar to this, which will bring up a dialog 'Connection Properties' if you left click it - this is not the one you want. Reboot if the applet is not visible.

  • Left click the network manager applet and select VPN Connections then click on your connection to connect.

  • If your new connection is greyed out and unselectable, or all you see is Manual Configuration...:

    • Backup /etc/network/interfaces to /etc/network/interfaces.original.
    • Delete all lines from /etc/network/interfaces not including the string "lo" (leaving two lines, probably the first two, beginning auto and iface).

    • Reboot.
  • If the above step leaves you with no internet connection at all, replace the original file and reboot.

Introduction to VPN

If you are familiar with VPN connections under Microsoft Windows, you might still benefit from reading this section. If you are familiar with VPN and the vagaries of how things work on modern computers (and particularly on Linux) you can skip it. Certainly, if you want to cut to the chase, head for part 2!

What is a VPN?

This section is very introductory, and if you know what a VPN is, you can skip it.

Many companies and universities (and some home users) run a 'local area network' (LAN) in their buildings, where many computers are connected together so that employees or students can share resources (printers, shared files, etc.). The people running these networks do not want the public (that is, the rest of the internet) to have access to their local network - considered private - so they secure it. The outside world can then not 'see in' (though the people on the local network can generally see out!).

It is often the case, however, that the organization will want its personnel to be able to 'see in' when they are out and about in the world - they may, for instance, need access to files they keep in their office. This is a textbook example of when the VPN comes in handy. VPN - 'virtual private network' - is a technology that allows a user physically outside the private network to bring themselves virtually inside it, thus gaining access to all of the resources that would be available were the user physically inside the network.

The organization will run a server which listens on a particular address for personnel to call in and request access. The user (i.e., you) will run a VPN client on their own computer, which will call up the VPN server and ask to be allowed to connect. Assuming the user can provide a recognized username and password when challenged by the server, the server and client machines will then negotiate a secure (i.e. encrypted) channel between them. Once this channel is established, the two machines can talk to each other without fear of anyone overhearing what they are saying, and your company boss will then think it's ok for you to upload/download sensitive company data over this channel.

Typically, once this channel is established, all communications from and to your computer will go over it.

For more information, see

What are the parts of a VPN?

VPN Servers

The VPN Server is run by your organization. You can run a VPNServer on Ubuntu, of course, but that is completely the other end of the system from what we're talking about here.

There is more than one way to VPN - any system that can establish a secure channel between you and your workplace, and then route all your communications over that channel, constitutes a VPN. Naturally, several groups have designed VPN 'protocols'. The one you will want to use will depend on the type that your organization uses, and to find that out you will have to ask your administrator. If you don't know offhand, but you do have your connection details, you might be able to ascertain the type of VPN protocol your organization uses because the different types require different connection details. This page covers the following types:

  • Microsoft's Point to Point Tunneling Protocol (PPTP), common with small business networks and Windows servers, requires host, username and password.

  • Cisco's VPN (VPNC) requires host, group username and group password, as well as username and password.

  • OpenVPN and IPSEC are not currently covered here.

VPN Clients

Once you have ascertained the VPN protocol you need to use, you'll need a client program to handle your end of the secure connection. For each protocol, there's a separate client program. They are not included with a default Ubuntu install. but they are easy to install (instructions below).

The VPN client will run invisibly in the background, maintaining your end of the VPN connection - that is, it doesn't have any windows or anything helpful like that for you to communicate with it. However, you're going to have to interact with it to tell it your connection details, and to tell it when to connect and disconnect.

Under Windows (XP, at least), you could do this by using the 'Add New Connection' wizard, and choosing 'connect to my workplace (VPN)'. Under Ubuntu, automatic set-up of this sort is developing fast, but you may have problems. If you do, this page should help you to solve them. Currently, things are somewhat in flux, and one of several different approaches may suit your particular situation. We will review them all below, and they are listed in the order that you should try them.


Let's just take a breath and summarize this introduction - to get your VPN connection up and running, you're going to need (a) your connection details, supplied to you by Bob in IT, (b) a VPN client that matches the protocol your organization uses, and (c) some way of managing that client. In the next part, we'll go through installing the bits you need, and configuring that connection. It can be tricky, so be ready to cry.

Installing and managing a VPN connection

For general information on how to install software in Ubuntu, look at InstallingSoftware. All packages listed in the following are available through the usual routes for package management - those marked AM can be reached through the 'Add/Remove applet'; those marked SPM must be installed using 'Synaptic Package Manager' ('Adept Manager' on Kubuntu or aptitude, apt-get). You must first enable the Universe software repository.

Configuring a connection (VPN Management)

Using NetworkManager

(NetworkManager) is a project to simplify Linux networking for desktop and laptop users. It supports VPN connections, and plugins are currently available for PPTP, VPNC and OpenVPN. It is packaged as Network Manager (AM) or nm-applet (SPM), and is installed by default as of Ubuntu 7.04.

By default, NetworkManager does not include any VPN plugins. You can choose to install:

  • the PPTP plugin, network-manager-pptp (SPM).

  • the Cisco VPNC plugin, network-manager-vpnc (SPM).

  • the OpenVPN plugin, network-manager-openvpn (SPM).

  • On Kubuntu Feisty you also need network-manager-gnome (SPM), due to bug 113505

NetworkManager appears in your notification area (normally next to the clock, in the top right hand corner of your screen) as an icon - either two monitors, one behind the other, or, if connected to wireless, a series of bars like a set of stairs. To configure a VPN connection, left click this icon and select VPN connections, Configure VPN and Add. You will be offered a choice of protocols on the second page of the wizard that pops up, but you will be offered only the protocols for which you've installed the appropriate plugin.

IconsPage/important.png NetworkManager only allows VPN connections if it is currently managing a connection. If your network interface is manually configured (in the Network Administration Tool under System/Administration) or in /etc/network/interfaces), it is not managed by NetworkManager. If the option for VPN connections is greyed out, NetworkManager is not managing a connection. Remove the connections from the Network Administration Tool, or manually edit /etc/network/interfaces. For a general case, it is safe to backup the interfaces file, and reduce its to only contain

auto lo
iface lo inet loopback

IconsPage/note.png NetworkManager connections are only available once a user has logged in. System-wide networking is planned for the next major version of NetworkManager, 0.7.0.

Debugging a connection

VPN plugins work by collecting the required information, and then passing it through to a program which runs the connection. The information for each connection is stored in the gconf preferences database, on a per-user basis. If you need to edit this manually, run Applications/System Tools/Configuration editor (or gconf-editor from a terminal). Connections are stored under system/networking/vpn_connections.

IconsPage/note.png It should not be possible to have two connections with the same name. If you find a connection will not start, it is possible you have two connections with the same name, and you should delete them manually using gconf-editor.

NetworkManager plugins log to syslog. Each plugin may have the option to enable debugging, so please enable it if you are submitting a bug report or trying to figure out why your connection does not establish.

Automatically starting your VPN connection on log-in

You can easily make the network manager applet start on log-in by adding the command nm-applet to your sessions. (Under System->Preferences->Session by default) However, this doesn't mean your configured connection fires up too. To make this happen you can add another command to your session startup programs:

/usr/lib/network-manager-vpnc/nm-vpnc-auth-dialog -s <service_name> -n <connection_name>

Connection name is the name of your connection and service_name can be one of the following:

If you are not sure what values are correct, then follow the steps described in Debugging a connection.

Note that you will be asked for your password and username when you have not stored those in the default gnome keyring and installed and configured libpam-keyring correctly.

Using KVpnc

This third-party tool is designed for KDE, but will run fine under GNOME too. It is packaged as KVpnc (AM). Once installed, you may find that when you run it it complains "cannot find su-to-root" or something like it - if so, it wants to be root, so run it with sudo or gksudo, e.g. open a terminal and enter sudo kvpnc.

REFERENCE INFORMATION Configuration files are stored in /etc/ppp/peers and prefixed kvpnc. I think they are copied from existing VPN connection files in that folder (if present). In other words, you are managing the same thing that PPTPconfig and Manual manage.

Manually configuring your connection

You should only attempt this if you are familiar with Linux administration and networking, or the above methods have failed.


PPTP support is available in the pptp-linux package. pptp is an extension to the PPP program, commonly used for dial-up modems. It uses a configuration file in the /etc/ppp/peers directory. Instructions on installing a program to configure PPTP connections are available from the pptpclient website.

To manually create a connection, you can create a file such as /etc/ppp/peers/myvpn:

remotename myvpn
linkname myvpn
ipparam myvpn
pty "pptp <host> --nolaunchpppd "
name <username>

# adopt defaults from the pptp-linux package
file /etc/ppp/options.pptp

You will also need an entry in the file /etc/ppp/chap-secrets to specify your password. It should be added at the bottom, and look like this:

<username> myvpn <password> *

You can then start the connection using the command pon myvpn nodetach, and stop it using Ctrl+C. In fact, that command line is a great command line to stick in a launcher on the toolbar (must be "Application in Terminal" type launcher).

Scripts in /etc/ppp/ip-up.d and /etc/ppp/ip-down.d are run on connection and disconnection, which gives you a chance to do routing using route or just log the state of things. Really, if you get as far as a script in /etc/ppp/ip-up.d actually triggering, you're probably basically there in any case so stop crying now. You might also be interested in /etc/resolv.conf where your current DNS is specified, and the commands ip and ss.


The Cisco VPNC client is available in the vpnc package (SPM).

Configuration files are stored in /etc/vpnc, which was protected to root on my installation so you might need to use sudo for all commands here. Copy example.conf to myvpn.conf

sudo cp /etc/vpnc/example.conf /etc/vpnc/myvpn.conf

and edit the new file to look like this:

IPSec gateway <host>
IPSec ID <group username>
IPSec secret <group password>
Xauth username <username>
Xauth password <password>

Note that you can leave out <password> if you want, and you will be prompted. Now, run vpnc-connect myvpn to start the connection - your output should look something like this:

> vpnc-connect myvpn
Connect Banner:
| Welcome to
| <Your Organization>
| *** VPN Service ***
| Your connection is now secure

VPNC started in background (pid: 7885)...
> vpnc-disconnect
Terminating vpnc daemon (pid: 7885)

You can then connect/disconnect with the commands vpnc-connect myvpn and vpnc-disconnect myvpn.

If you have a .pcf configuration file from a Windows® installation of the Cisco VPN client, it is easiest to convert this file. Ubuntu Geek has a tutorial on how to set up a Cisco VPN on Ubuntu 9.04 Jaunty. The steps are descriptive, even though there is some compiling involved.


The OpenVPN client is part of the openvpn package (SPM).

Installing OpenVPN is outside the scope of this document, but it is well documented at the OpenVPN website.

Extra credit: how VPN works

A little knowledge of what goes on "under the hood" can be the difference between connection and confusion. These examples assume a PPTP VPN connection.

Bringing up the 'tunnel'

Your client calls over your normal connection (e.g. your wired/wireless link, e.g. eth0, eth1) to the VPN server. They negotiate authentication so they both believe each other are who they say they are. They exchange encryption information, and can now talk to each other on a narrow channel (a 'tunnel') without anyone else overhearing by sending what they want to say to each other in encrypted packets. This is very interesting, but is useless until some other application wants to send data over this encrypted line. This works as follows.

Rerouting communications

When an application on your box asks linux to send a packet to some destination host (e.g., the following occurs:

  • is resolved to by your DNS server, which is specified in /etc/resolv.conf
  • Linux decides where to send that packet first by looking up in the routing table - type route into a terminal to see the table

  • typically, it is routed to your primary interface (NIC) first. that interface will then route it to probably your router. the router will then probably send it your modem, which will pass it up to your ISP. from there, it's anybody's guess, but the game continues, route by route by route, until it (hopefully) reaches the server at

Note, you can test name resolution ( -> by typing ping at the terminal prompt. You can test packet routing by executing tracepath (your mileage may vary).

Once a VPN tunnel has been established, the above process will carry on unaffected, unless packets are re-routed over the new tunnel. This is done by adding an entry to your routing table, pointing (often all) packets at your tunnel, your point-to-point interface, ppp0 probably. Now, when an application asks linux to send a packet to, linux routes it to ppp0. ppp0 encrypts it and readdresses it, so it now gets sent to the VPN server (via the usual non-tunnel route, eth1 or whatever). when the VPN server receives it, it unencrypts it to extract the original packet, and sends it off into its private network (do you see how we just went over the tunnel there?). Hence, if you now ask for in your browser, the request goes...

  • ppp0 (your end of the VPN tunnel), encryption into a container packet, and readdress to your VPN server.
  • eth0/1, off into the internet as usual.
  • reaches the VPN server, unencryption, and back to its original address,
  • off into the private network.
  • out into the internet again, to


  • Your VPN can connect/disconnect successfully, and have no effect on how the rest of your communications function, unless traffic is routed over the VPN (tunnel).
  • Bringing up the VPN, thus, involves both establishing that secure link, and doing the appropriate re-routing.
  • You can add/remove routes in script using route add and route del.

  • You can have scripts run automatically as a connection (e.g. VPN) is brought up and down by placing them in /etc/ppp/ip-up.d and /etc/ppp/ip-down.d
  • You can check the current route table by typing route in a terminal.

  • The connection client may re-route automatically unless you tell it not to (pon has an option nodefaultroute i think).
  • (this happened to me) If you route all traffic over the tunnel once the VPN connection is up, even your encrypted packets will get routed over the tunnel. Thus, your original packet A will get encrypted into A*, and sent over the tunnel, encrypted into A**, sent over the tunnel, etc... (see below under 'Packet recursion').
  • Thus, a typical route table after connection of the VPN will have traffic sent over the tunnel by default, unless it's headed for your VPN server, in which case it's routed straight to your interface card (e.g. eth1).
  • More advanced routing is possible, with some traffic going over the tunnel, and some going out as usual, but this is not covered here.
  • Let's face it, we've barely covered routing at all, but I just wanted to give some hints... Smile :)



  • The PPTP-client website has some great troubleshooting tips. Start there, even if you're using NetworkManager's PPTP support.

  • VPN stops working after < 1 min, then disconnects same subnets for client and VPN network

    • Make sure that the IP subnets on your client machine and the VPN network you want to connect to are different, i.e. Client 192.168.1.x VPN network 192.168.2.x
  • MPPE required, but MS-CHAP[v2] auth not performed in debug log messages from pon

    • Your authentication data is missing from the file /etc/ppp/chap-secrets
      • Use pptpconfig to correct this, by trying to connect to the connection and entering your data and asking it to store it
      • Enter a new line in /etc/ppp/chap-secrets reading "username connname password-plaintext *"
  • Packet recursion

    • Symptoms - client appears to connect, but VPN does not work (you can't access private resources), and it probably disconnects shortly after connection (30-120 seconds).
    • Test for packet recursion - open a terminal, and while the connection is 'up', type 'ip -s link' 3 or 4 times. If you are suffering packet recursion, one of your listed interfaces (probably ppp0) will show 'TX bytes' increasing rapidly on each call to ip (megabytes per second).
    • Cause - packets are being routed back on themselves, and so a single packet is looping round and round through the same interface.
    • See

    • This is caused because VPN traffic (which should go raw to the VPN server, rather than going over the tunnel) starts going through the tunnel once it is established. This is stupid, since it this traffic that represents the tunnel, so it can't actually go through the tunnel - see 'how it works'.
  • Cannot determine ethernet address for proxy ARP

    • This message occurs during PPTP connection but does not indicate a problem - do not worry about it.


VPNClient (last edited 2015-03-26 17:46:06 by port-212-202-227-184)