How do I hook up to the NX VPN ?
Follow these steps :
Elect a VPN endpoint in your network. The endpoint needs the following
software features :
You no longer need a dedicated user account to run the client side
of the VPN. The client side runs a pppd process and a ssh process ;
the pppd process needs root privileges, and using a SUID setup would
not gain you much security. If you don't trust the ssh process,
you can create an user dedicated to the execution of the ssh tunnel
(this will be explained later), but that's not really necessary
(if you think of a security flaw induced by running the ssh client
as root, please tell us!). On the other hand, running the
VPN-related processes (pppd and ssh, plus eventually pty-redir)
allow easier accounting of CPU and memory ressources usage (thanks
to Sandman for this tip).
Create a SSH public key. Use ssh-keygen ; specify an empty passphrase,
and put it in /root/.ssh/vpnkey (for instance). If you want to run
the client with a regular user (as opposed to root), create the user,
and create the key as this user. This user should have an invalid
password (i.e., the password field in /etc/passwd should be * so it
will be impossible to login as this user).
Determine your VPN IP address. It should be like 192.168.X.Y, and your
network should not have already been used by another host on the NX VPN.
Check the list
to see used and available IP addresses ranges.
Determine your VPN host name and domain name. You can choose any domain
as long as it has not been already taken, and any host name. You need
a symbolic host name (like "mozart"), and if you want to be part
of the NX DNS, you need a "real" domain name, like "music.nx".
Send your public key (vpnkey.pub), your desired VPN IP address, domain
and host names, to the maintener of a VPN backbone host. You can mail
skaya if you want to link to
the main NX node (vpn-core). You should also
choose whether you want to be a leaf or a node. You're a leaf if your local
VPN endpoint is the only host you want to connect. You're a node if
you have a whole network behind your endpoint.
Wait for the maintener confirmation. (S)he should give you
a VPN endpoint specification (like email@example.com),
and if you're a node, a local ASN, a router-id, and the coordinates of
a BGP neighbor (another ASN and an IP address). If you plan to link
to the main NX node, the endpoint is firstname.lastname@example.org ; your ASN
will probably be derived from your IP address - if you hold
192.168.XXX.*, your ASN will be 65XXX (i.e. 192.168.42.0 will yield
65042). The router-id will probably be XXX.XXX.XXX.XXX (220.127.116.11
in the previous example). Note that if the subnet mask of your network
is smaller than 24 bits, these figures will vary.
Create a PPP configuration file, /etc/ppp/peers/vpnenix (you can name
it differently, without any problem ; just replace "vpnenix" with whatever
you want in the following instructions). This file should contain the
following lines : (download)
SSH client - the current main endpoint supports both SSH1 and SSH2 connections,
but we use SSH1 scheme for RSA key authentication. So, be sure to generate
SSH1 RSA keys (the default when running ssh-keygen). If your client version
defaults to protocol version 2, specify that you want to use version 1.
If you don't know the answer to thses questions, just run ssh and check
if there are -1 and -2 flags ; if these flags exist with your ssh client,
you will need to specify -1 when running the ssh connection. This will
be remembered later, so don't worry. Anyway, you need a decent SSH client
(just the ssh binary is necessary, and ssh-keygen at setup time ; once
you have generated the key, ssh-keygen is no longer necessary).
PPP network interface, able to operate on arbitrary device (not limited
to serial devices). The current instructions use a very simple and
straightforward setup, requiring the "pty" option. Check your pppd
manpage to verify that your version supports the "pty" option. If
it doesn't, either upgrade your pppd, or use the older pty-redir
If you want to use the pty-redir setup, you need decent POSIX ttys.
If you don't know if you have decent POSIX ttys, try to compile
pty-redir (remember : if your pppd supports the "pty" option, you
don't need that). All recent pppd for Linux and BSD derivates support
the pty option ; for Windows NT I don't know if a pppd daemon exists.
pty 'sleep 1 ; ssh -i /root/.ssh/vpnkey -t email@example.com'
If you have a SSH2 client which defaults to SSH2 key negotiation,
add -1 just after the -t option, to force SSH1 key exchange. Else
your key won't be used and you won't be able to login.
If you use a dedicated user for the ssh tunnel, replace the pty stanza
with : (replace vpnuser with the real name of the user ; you may also want
to modify the path to the key)
pty 'sleep 1 ; su vpnuser sh -c "ssh -i .ssh/identity -t firstname.lastname@example.org"'
If your pppd does not support the pty option, download pty-redir-nx,
compile it for your system, and start pppd that way :
pppd `/usr/local/bin/pty-redir-nx /usr/bin/ssh -e none -t -o -i
/root/.ssh/vpnkey email@example.com` call vpn
and remove or comment the pty option in the peer file. Remove
the persist option, too.
If you want to reconnect automatically, I suggest you add nodetach
option, and write a little shell script which starts pppd automatically
when it quits :
while true ; do pppd lostofoptions nodetach ; done.
If you're behind a socks server or any other firewall or stuff
that requires you to run something special to start ssh sessions,
add every needed action required ; eventually you can put these
in a shell script and start the shell script instead of ssh directly.
The "sleep 1" helps mitigating connection errors ; instead of causing
many connection attempts if the server becomes unavailable, it will limit
the rate of errors to one per second. You can increase the delay if you
want, or suppress it totally (but suppressing it won't give you other
avantages than gaining 1 second out of about 10 seconds for VPN
activation ; and it forks one process less...).
Note that you don't need anymore to specify a user or domain, and
you don't need a password in /etc/ppp/pap-secrets : all authentication is
done thru your SSH RSA key.
If you don't want to use the pty option of pppd (if you CAN'T, actually),
fetch pty-redir-nx (a modified pty-redir), and compile it.
Fetch the vpn-connect.sh script, and edit it to add the path to pty-redir-nx,
and the endpoint specification (vpnuser@vpnhost) that the maintenir did
give to you.
All these tools should be available for vpnuser.
Now try the exact same command line as used in the pty option of pppd,
i.e. "ssh -i /root/.ssh/vpnkey -t -1 firstname.lastname@example.org". If you
did setup a dedicated user, enter the full command line "su vpnuser sh -c...".
SSH should ask you to validate the host key. This is very important to
run this step, because you need to validate the key of the server. Your
VPN connection won't work if you don't do it, because the pty
process will stay stuck at the "Accept server key?" dialog. If it asks
a password, you did something wrong with
your SSH keys. If it starts spitting strange codes (PPP negociation, in
fact) you're OK. Wait for it to calm down and go on (it should take about
30 seconds, depending on LCP parameters on the VPN server).
If you use a dedicated user, make sure he can run pppd
(you may want to give him a suid copy
of pppd, or make him member of group dip, for instance).
If you use a regular (pty option based) setup, just
run "pppd call vpnenix" and you're connected.
If you use a pty-redir setup, run vpn-connect.
You should now be connected to the NX VPN.
For the pty-redir setup,
to ensure automatic reconnection, and connection at host bootup,
insert the following line in /etc/inittab :
nx:23:respawn:/bin/su - vpnuser ~vpnuser/vpn-connect.sh >& /var/log/vpn.log
And issue a telinit q to reload inittab. Enjoy!
How do I reach the rest of the NX VPN?
If you're a leaf, just add a static route :
route add -net 192.168.0.0 netmask 255.255.0.0 gw remotevpnhost
Where remotevpnhost can be obtained from "ifconfig", looking for the ppp
entry matching the VPN. On the NX core, it's 192.168.0.179 ; note that
there are very clean ways to add routes and do other stuff automatically
when the VPN comes up. You can use ip-up scripts ; check your pppd manpage
for more information. If you're using Debian, I would recommand adding
ipparam vpnenix to the peer file, and placing a script
in /etc/ppp/ip-up.d, checking for the value of ipparam to add the static
route and do other stuff. Note that routes don't need to be deleted
thru ip-down mechanism : they will be automatically removed when the
interfaces comes down ; but other things (iptables, iproute2 rules...)
need to be explicitly removed, so don't forget them.
If you're a node, things are trickier. In a nutshell : configure a BGP routing
process (we suggest zebra) with the supplied ASN and router-id. Add the
specified neighbor. Create routing entries for your local networks. If
you configured the neighbor properly, many VPN routes should start populating
your tables. That scares you ? Check this introduction
to Zebra to learn more.
How do I setup DNS?
This is dealt with in another document, located here.
Evolution of this document : I should split explanations between regular setup
and pty-redir based setup. If nobody plans using pty-redir setup, I can delete
it completely, as it is more cumbersome than the pty option setup. Also, any
security expert opinion on the root-started ssh tunnel VS. regular user-started
ssh tunnel will be welcome.