Usage Notes

[ Note by your friendly OpenBSD pptp port maintainer:
Most examples in this file are quite Linux-centric. See the section
EXAMPLE CONFIGURATION FOR OPENBSD below for an example that focuses
on OpenBSD exclusively. ]

pptp is started as a psuedo-tty child process using pppd's pty option:

	pppd call provider [pppd-options] \
	pty "/usr/sbin/pptp hostname --nolaunchpppd [pptp-options]"

where hostname is the host name or IP address of the PPTP server.

pptp can also start pppd itself:

	pptp hostname [pptp-options] [pppd-options]

Note the unusual order of arguments, the hostname comes before the
pptp options, and the pppd options come last.

So, for example:

	pptp my.pptp.host debug name cananian \
	remotename ntdialup 172.18.0.2:172.18.0.3

	route add -net 172.18.0.0 netmask 255.255.0.0 gw 172.18.0.3

You will see three pptp-related processes in your process list: a call
manager, a GRE/PPP en/decapsulator, and pppd.  To shut down the pptp
connection, kill the pppd process.

NOTE THAT PPTP MUST BE RUN AS ROOT.  This is so that it can generate
GRE packets using a raw socket.

Most trouble with pptp will probably be due to incorrect pppd
configuration.  Be sure you thoroughly understand MS-CHAP support in
pppd.  Use the 'debug' option to pppd to log connection information;
this will help you trouble-shoot the pppd side of pptp.

See the project web site for diagnosis assistance.

QUIRKS HANDLING:

Some ADSL providers and some ADSL hardware are buggy or not conforming
to the RFC, and require special handling.  To this end, pptp supports
a 'quirks' mechanism.  Currently, only '--quirks BEZEQ_ISRAEL' is
defined, for connecting to Bezeq (the Israeli phone company) ADSL
service.

Only *some* of the equipment used by Bezeq needs this option, but even
the equipment that does not need it works fine with it.  If you use
Bezeq, you probably want the '--quirks BEZEQ_ISRAEL' switch.

More information on Bezeq's ADSL service can be found at
http://vipe.technion.il/~mulix/adsl-howto.txt and
http://damyen.technion.ac.il/~dani/adsl-howto.txt.

TESTING MULTIPLE TUNNELS:

For testing of PPTP servers, the client can be used to establish
multiple tunnels from multiple IP addresses.  The addresses must be
routable; this is something you'd do on a local area network.

1. use an address pool on a concentrator.

2. write an ip-up script (e.g. /etc/ppp/ip-up.local or /etc/ppp/ip-up.d)

	#!/bin/sh
	export PATH=/sbin:/usr/sbin:/bin:/usr/bin
	REALDEVICE=$1
	PEERADDR=$6
	ifconfig ${REALDEVICE} dstaddr ${PEERADDR}

The script performs an "ifconfig pppx dstaddr xx.xx.xx.xx" where
xx.xx.xx.xx is the private address of the concentrator so that the
routing works without having to do iptables or ipchains.  The address
used is given on the pptp command line.

3. create distinct source interfaces with:

        ifconfig eth0:n xx.xx.xx.xx netmask yy.yy.yy.yy 

Where "n" is the alias interface number, "xx.xx.xx.xx" is the new
address, and "yy.yy.yy.yy" is the network mask.

4. connect with

	pptp concentrator --bind xx.xx.xx.xx name \
        xx remotename yy ipparam yy.yy.yy.yy 
                                       ^ (private address of concentrator).

Where "xx.xx.xx.xx" is the address of the source interface, "xx" is
the local name of the tunnel, "yy" is the remote name of the tunnel,
and "yy.yy.yy.yy" is the private address of the concentrator.  This is
passed to the ip-up script as the sixth argument.

See also the following test scripts;

test-multiple-tunnels-1.sh  creates multiple source interfaces
test-multiple-tunnels-2.sh  creates multiple tunnels


EXAMPLE CONFIGURATION FOR OPENBSD:

On OpenBSD, pptp uses the userspace ppp(8) implementation
by default, instead of using pppd(8). This is a compile-time option
hardcoded in the port's Makefile, and it is not recommended that you
change this unless you really have a reason to do so. If your VPN
requires mppe/mppc in conjunction with pptp, ppp(8) is your
only option anyway since pppd(8) does not support mppe/mppc.

This example assumes that you want to configure a gateway running
OpenBSD to provide PPTP VPN access to a remote network for all hosts
on your internal LAN. While this may not match your situation at
all, you will hopefully gather enough hints you can use for your
own setup.

Let us assume that the VPN server is called vpn-gateway.net,
and that the default route of our OpenBSD box is 42.42.42.42.
The remote network is 10.42.0/16; all traffic to this network
should go through the VPN tunnel.

Having ppp start pptp seems to be working much better than the
other way round. So first, put something like this into /etc/ppp/ppp.conf
to connect to the vpn gateway:

  default:
	set log Phase Chat LCP IPCP CCP tun command
  vpn:
	set device "!/usr/local/sbin/pptp --nolaunchpppd vpn-gateway.net"
	set authname User
	set authkey MySecret
	set mppe 128 stateless

Next, you need to configure routing in /etc/ppp/ppp.linkup.
Assuming vpn-gateway.net resides inside 10.42.0/16, we have to add a host
route pointing to vpn-gateway.net in order to avoid a chicken-and-egg
problem once packets to 10.42.0/16 are routed through the tunnel.
(Of course, this also applies if you need to configure the tunnel as
your default route, but that is not covered in this example.)

We also load packet filter anchors for the vpn interface here.
More on that later.

/etc/ppp/ppp.linkup:

  vpn: 
    ! sh -c "/sbin/route add -host vpn-gateway.net 42.42.42.42"
    ! sh -c "/sbin/route add -net 10.42.0.0 -netmask 255.255.0.0 HISADDR"
    ! sh -c "/sbin/pfctl -a vpn -f /etc/pf.conf.vpn"

Commands in ppp.linkdown simply undo changes made in ppp.linkup.

/etc/ppp/ppp.linkdown:

  vpn:
    ! sh -c "/sbin/pfctl -a vpn -F all"
    ! sh -c "/sbin/route delete -net 10.42.0.0 -netmask 255.255.0.0 HISADDR"
    ! sh -c "/sbin/route delete -host vpn-gateway.net 42.42.42.42"

To make pf aware of the vpn anchors, put these lines into the
nat and filter sections of /etc/pf.conf, respectively:

  nat-anchor	vpn
  anchor	vpn

Now define vpn anchor rules in /etc/pf.conf.vpn:

  int_if=xl0
  vpn_if=tun0

  nat on $vpn_if from $int_if:network to any -> ($vpn_if)

  pass out on $vpn_if keep state

  # Allow ping from remote, and explicitly make sure our replies are
  # routed back through the tunnel.
  pass in on $vpn_if reply-to ($vpn_if vpn-gateway.net) \
	inet proto icmp icmp-type echoreq keep state

  # Same for ssh.
  pass in on $vpn_if reply-to ($vpn_if vpn-gateway.net) proto tcp \
	from any to ($vpn_if) port ssh flags S/SA keep state


Connect by running:

	ppp -ddial vpn

To terminate the connection, kill the ppp process. It creates a PID
file in /var/run/tunX.pid, where X is the number of the tun device used.

$Id: USING,v 1.6 2003/02/15 04:32:50 quozl Exp $	
