How do I hook up to the NX VPN ?

1. Elect a VPN endpoint in your network. The endpoint needs the following software features :
• 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 setup.
• 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.
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)

noauth
pty 'sleep 1 ; ssh -i /root/.ssh/vpnkey -t vpn@vpn-core.enix.org'
persist
connect-delay 300000
silent
holdoff 30
maxfail 0

9. 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.
10. 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 vpn@vpn-core.enix.org"'

11. 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

    .
12. 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.
13. 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...).
14. 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.
15. 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.
16. 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).
17. 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).
18. If you use a regular (pty option based) setup, just run "pppd call vpnenix" and you're connected.
19. If you use a pty-redir setup, run vpn-connect. You should now be connected to the NX VPN.
20. 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?

route add -net 192.168.0.0 netmask 255.255.0.0 gw remotevpnhost

ipparam vpnenix

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?