SSH VPN integration for NetworkManager
Clone or download
danfruehauf Update debugging section in
Spinning up `nm-ssh-service --debug` won't work any more
Latest commit b6593f7 May 18, 2018
Failed to load latest commit information.
appdata appdata: rename the xml file Apr 28, 2016
auth-dialog all: remove useless defines Oct 23, 2015
debian service: use the NM API instead of dbus-glib to send configuration Aug 31, 2015
images updated screenshots Feb 25, 2013
m4 added proper ignores Feb 19, 2013
po appdata: rename the xml file Apr 28, 2016
properties No default route button Apr 16, 2017
src Support multiple connections Dec 7, 2017
test Improve vagrant provisioning Nov 14, 2016
.gitignore appdata: rename the xml file Apr 28, 2016
AUTHORS * modified AUTHORS Feb 6, 2013
COPYING nm-ssh: first commit imported from nm-openvpn Feb 4, 2013
ChangeLog not maintaining spec and Changelog anymore in git repository Jul 6, 2013 appdata: rename the xml file Apr 28, 2016
NEWS nm-ssh: first commit imported from nm-openvpn Feb 4, 2013
NetworkManager-ssh.spec service: use the NM API instead of dbus-glib to send configuration Aug 31, 2015
README changes to conform with Fedora packaging guidelines Mar 21, 2013 Update debugging section in May 18, 2018 release: bump version to 1.2.0 Apr 22, 2016
gnome-mime-application-x-ssh-settings.png nm-ssh: first commit imported from nm-openvpn Feb 4, 2013 nm-ssh: first commit imported from nm-openvpn Feb 4, 2013 nm-ssh: first commit imported from nm-openvpn Feb 4, 2013 nm-ssh: first commit imported from nm-openvpn Feb 4, 2013
nm-ssh-service.conf Support multiple connections Dec 7, 2017 Support multiple connections Dec 7, 2017 nm-ssh: first commit imported from nm-openvpn Feb 4, 2013


Happy to introduce SSH VPN integration for NetworkManager.

It is still very much work in progress, so please do open me issues with bugs or future requests. If there will be enough interest, I'll definitely continue developing it. I still have enough cleanups I need to perform code wise.

I've forked the work of NetworkManager-ssh from NetworkManager-openvpn.


Because we can!

SSH VPN can be used just anywhere!

So what does it do?

Basically NetworkManager-ssh integrates OpenSSH tunnel capabilities with NetworkManager and provides you with the easiest of all VPNs, as OpenSSH lives on almost any *nix machine today.



If you're using Fedora 22 or later, you can simply run:

# dnf install NetworkManager-ssh-gnome

If you're using Fedora 22 or later, with KDE Plasma 5 run:

# dnf install NetworkManager-ssh plasma-nm-ssh

That will set you up with NetworkManager and the traditional GNOME interface. I am the current maintainer of the package for Fedora.

On older versions of Fedora or CentOS, you can run the following after cloning the repository:

$ autoreconf -fvi && ./configure && make rpm

Enjoy your new RPM.


On recent Debian/Ubuntu distributions you should be able to install with:

# apt-get install network-manager-ssh

In case you want to build the package for Debian/Ubuntu, you can use the complimentary packaging this repository provides, but please do not open bugs about it on this GitHub issue tracker. The correct thing to do is to use the upstream packages provided with the distribution and open bugs on the distribution issue tracker.

Building a .deb should be straight forward with:

# apt-get install libnm-glib-dev libnm-glib-vpn-dev libnm-util-dev libnm-dev libnma-dev libgnome-keyring-dev dh-autoreconf libgtk-3-dev sshpass
$ autoreconf -fvi && ./configure && make deb

Enjoy your new .deb. (It should show up in the directory you git cloned from.)

Older Distributions

On old distributions with NetworkManager < 0.9.10, such as Ubuntu 14.04, use the 0.9.3 tag:

$ git checkout 0.9.3
$ autoreconf -fvi && ./configure && make deb


Please edit /etc/dbus-1/system.d/org.freedesktop.NetworkManager.conf and add the line:

<allow send_destination="org.freedesktop.NetworkManager.ssh"/>

Make sure your target host is known in ~/.ssh/known_hosts. If it's not there, you should add it manually or by SSHing to it:

$ ssh root@TARGET_HOST
The authenticity of host 'TARGET_HOST' can't be established.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'TARGET_HOST' (ECDSA) to the list of known hosts.

If all went right, you should have a new VPN of type SSH when creating a new VPN.


When things go wrong and you can't really figure out what's happening, have a look at /var/log/messages as you spin up the connection. You should be able to tell what is going wrong.

Server side configuration

Even though this is a bit off-topic, I've decided to cover it anyway.

On the server, you'll need to enable in /etc/ssh/sshd_config:


Enable kernel packet forwarding:

echo 1 > /proc/sys/net/ipv4/ip_forward

In terms of firewall configuration, I recommend looking at the "standard" way of editing firewall rules on your distribution. These however, should work on most GNU/Linux distributions.

Tun devices:

iptables -I FORWARD -i tun+ -j ACCEPT
iptables -I FORWARD -o tun+ -j ACCEPT
iptables -I INPUT -i tun+ -j ACCEPT

Tap devices:

iptables -I FORWARD -i tap+ -j ACCEPT
iptables -I FORWARD -o tap+ -j ACCEPT
iptables -I INPUT -i tap+ -j ACCEPT

Please use these firewall rules as a reference only.

Don't forget to replace EXTERNAL_INTERFACE with your WAN interface (eth0, ppp0, etc).

Port Binding

If you're only after port binding (-L or -R with SSH), you can still use NetworkManager-ssh to perform that, although two limitations still exist:

  • You will still have a full open tunnel to the destination machine
  • NetworkManager allows to open only one VPN connection at a time, so it means one port bind at any given time

So this is how it's done, in the Advanced Dialog tick Extra SSH options and add your line, something in the form of:

-L 3306:localhost:3306

And to prevent networking from being routed through the VPN, tick Do not replace default route.

That's it, you're done.

Authenticating with SSH Agent

You will need ssh-agent running before you start NetworkManager-ssh.

How do you know if you have ssh-agent running? Simply run:

$ env | grep SSH

You should see something similar to that.

NetworkManager-ssh probes for the ssh-agent that is attached to your session and authenticates with its socket.


Known Hosts

If the destination host is not in your known_hosts file, things will not work, unless you add in the extra options box:

-o StrictHostKeyChecking=no

Behind the scenes - how does it actually work??

In order to open a tunnel OpenSSH VPN, all that you have to do is run:

# This is the WAN IP/hostname of the remote machine

# Remote username will usually be root, or any other privileged user
# who can open tun/tap devices on the remote host

# Remote IP in the tunnel

# Local IP in the tunnel

# Netmask to set (on both sides)

# SSH port to use

# MTU for tunnel

# Extra SSH options, these would give us some nice keep alive
EXTRA_OPTS='-o ServerAliveInterval=10 -o TCPKeepAlive=yes'

# Remote tunnel device (tun100/tap100)
# TUNNEL_TYPE is 'point-to-point' for tun and 'ethernet' for tap

# Local tunnel is calculated depending on what devices are free
# The following loop iterates from 0 to 255 and finds a free
# tun/tap device
for i in `seq 0 255`; do ! ifconfig $DEV_TYPE$i >& /dev/null && LOCAL_DEV=$i && break; done

ssh -f -v -o Tunnel=$TUNNEL_TYPE -o NumberOfPasswordPrompts=0 $EXTRA_OPTS \
	"/sbin/ifconfig $DEV_TYPE$REMOTE_DEV $REMOTE_IP netmask $NETMASK pointopoint $LOCAL_IP up" && \
/sbin/ifconfig $DEV_TYPE$LOCAL_DEV $LOCAL_IP netmask $NETMASK pointopoint $REMOTE_IP up

That's actually an edited export file of a working SSH VPN configuration I have from NetworkManager.

This will create a tunnel of<-> on tun100 on both machines. If forwarding is enabled on that SSH server, you'll get pass-through internet easy.

People I'd like to thank

  • Thomas Young - First user!
  • Whoopie - For nice debian support and testing
  • Oren Held - Invaluable feedback and testing
  • Lubomir Rintel (@lkundrak)- Keeping this repository up to date with upstream NetworkManager, assisting with Fedora packaging
  • Lennart Weller (@lhw) - Debian packaging


Choosing a connection type:

Main dialog:

Advanced dialog: