How do I hook up to the NX VPN ?

Follow these steps :
  1. Elect a VPN endpoint in your network. The endpoint needs the following software features :
  2. 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).
  3. 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).
  4. 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.
  5. 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".
  6. 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.
  7. Wait for the maintener confirmation. (S)he should give you a VPN endpoint specification (like myvpn@bigfatserver.worldcompany.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 vpn@vpn-core.enix.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 (42.42.42.42 in the previous example). Note that if the subnet mask of your network is smaller than 24 bits, these figures will vary.
  8. 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)
  9. noauth
    pty 'sleep 1 ; ssh -i /root/.ssh/vpnkey -t vpn@vpn-core.enix.org'
    persist
    connect-delay 300000
    silent
    holdoff 30
    maxfail 0
  10. 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.
  11. 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)
  12. pty 'sleep 1 ; su vpnuser sh -c "ssh -i .ssh/identity -t vpn@vpn-core.enix.org"'
  13. 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 vpn@vpn-core.enix.org` 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
    .
  14. 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.
  15. 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...).
  16. 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.
  17. 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.
  18. Now try the exact same command line as used in the pty option of pppd, i.e. "ssh -i /root/.ssh/vpnkey -t -1 vpn@vpn-core.enix.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).
  19. 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).
  20. If you use a regular (pty option based) setup, just run "pppd call vpnenix" and you're connected.
  21. If you use a pty-redir setup, run vpn-connect. You should now be connected to the NX VPN.
  22. 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.
skaya@enix.org