add handle_events() function
[ppp.git] / README.sol2
1 This file describes the installation process for ppp-2.3 on systems
2 running Solaris 2.  The Solaris 2 and SVR4 ports share a lot of code
3 but are not identical.  The STREAMS kernel modules and driver for
4 Solaris 2 are in the svr4 directory (and use some code from the
5 modules directory).
6
7 NOTE: Although the kernel driver and modules have been designed to
8 operate correctly on SMP systems, they have not been extensively
9 tested on SMP machines.  Some users of SMP Solaris x86 systems have
10 reported system problems apparently linked to the use of previous
11 versions of this software.  I believe these problems have been fixed.
12
13
14 Installation.
15 *************
16
17 1. Run the configure script and make the user-level programs and the
18 kernel modules.
19
20         ./configure
21         make
22
23 If you wish to use gcc (or another compiler) instead of Sun's cc, edit
24 the svr4/Makedefs file and uncomment the definition of CC.  You can
25 also change the options passed to the C compiler by editing the COPTS
26 definition.
27
28 2. Install the programs and kernel modules: as root, do
29
30         make install
31
32 This installs pppd, chat and pppstats in /usr/local/bin and the kernel
33 modules in /kernel/drv and /kernel/strmod, and creates the /etc/ppp
34 directory and populates it with default configuration files.  You can
35 change the installation directories by editing svr4/Makedefs.
36
37 If your system normally has only one network interface, the default
38 Solaris 2 system startup scripts will disable IP forwarding in the IP
39 kernel module.  This will prevent the remote machine from using the
40 local machine as a gateway to access other hosts.  The solution is to
41 create an /etc/ppp/ip-up script containing something like this:
42
43         #!/bin/sh
44         /usr/sbin/ndd -set /dev/ip ip_forwarding 1
45
46 See the man page for ip(7p) for details.
47
48 Dynamic STREAMS Re-Plumbing Support.
49 ************************************
50
51 Solaris 8 includes dynamic re-plumbing support. With this, modules
52 below ip can be inserted, or removed, without having the ip stream be
53 unplumbed, and re-plumbed again. All states in ip for an interface
54 will therefore now be preserved. Users can install (or upgrade)
55 modules like firewall, bandwidth manager, cache manager, tunneling,
56 etc., without shutting the machine down.
57
58 To support this, ppp driver now uses /dev/udp instead of /dev/ip for
59 the ip stream. The interface stream (where ip module pushed on top of
60 ppp) is then I_PLINK'ed below the ip stream. /dev/udp is used because
61 STREAMS will not let a driver be PLINK'ed under itself, and /dev/ip is
62 typically the driver at the bottom of the tunneling interfaces
63 stream.  The mux ids of the ip streams are then added using
64 SIOCSxIFMUXID ioctl.
65
66 Users will be able to see the modules on the interface stream by, for
67 example:
68
69     pikapon% ifconfig ppp modlist
70     0 ip
71     1 ppp
72
73 Or arbitrarily if bandwidth manager and firewall modules are installed:
74
75     pikapon% ifconfig hme0 modlist
76     0 arp
77     1 ip
78     2 ipqos
79     3 firewall
80     4 hme
81
82 Snoop Support.
83 **************
84
85 This version includes support for /usr/sbin/snoop. Tests has been done
86 on both Solaris 7 and 8. Only IPv4 and IPv6 packets will be sent up to
87 stream(s) marked as promiscuous, e.g, snoop et al.
88
89 Users will be able to see the packets on the ppp interface by, for example:
90
91     snoop -d ppp0
92
93 See the man page for snoop(1M) for details.
94
95 IPv6 Support.
96 *************
97
98 This is for Solaris 8 and later.
99
100 This version has been tested under Solaris 8 running IPv6. As of now,
101 interoperability testing has only been done between Solaris machines
102 in terms of the IPV6 NCP. An additional command line option for the
103 pppd daemon has been added: ipv6cp-use-persistent.
104
105 By default, compilation for IPv6 support is not enabled.  Uncomment
106 the necessary lines in pppd/Makefile.sol2 to enable it. Once done, the
107 quickest way to get IPv6 running is to add the following somewhere in
108 the command line option:
109
110         +ipv6 ipv6cp-use-persistent
111
112 The persistent id for the link-local address was added to conform to
113 RFC 2472; such that if there's an EUI-48 available, use that to make
114 up the EUI-64.  As of now, the Solaris implementation extracts the
115 EUI-48 id from the Ethernet's MAC address (the ethernet interface
116 needs to be up).  Future works might support other ways of obtaining a
117 unique yet persistent id, such as EEPROM serial numbers, etc.
118
119 There need not be any up/down scripts for ipv6, e.g. /etc/ppp/ipv6-up
120 or /etc/ppp/ipv6-down, to trigger IPv6 neighbor discovery for auto
121 configuration and routing.  The in.ndpd daemon will perform all of the
122 necessary jobs in the background. /etc/inet/ndpd.conf can be further
123 customized to enable the machine as an IPv6 router. See the man page
124 for in.ndpd(1M) and ndpd.conf(4) for details.
125
126 Below is a sample output of "ifconfig -a" with persistent link-local
127 address.  Note the UNNUMBERED flag is set because hme0 and ppp0 both
128 have identical link-local IPv6 addresses:
129
130 lo0: flags=1000849<UP,LOOPBACK,RUNNING,MULTICAST,IPv4> mtu 8232 index 1
131         inet 127.0.0.1 netmask ff000000 
132 hme0: flags=1000843<UP,BROADCAST,RUNNING,MULTICAST,IPv4> mtu 1500 index 2
133         inet 129.146.86.248 netmask ffffff00 broadcast 129.146.86.255
134         ether 8:0:20:8d:38:c1 
135 lo0: flags=2000849<UP,LOOPBACK,RUNNING,MULTICAST,IPv6> mtu 8252 index 1
136         inet6 ::1/128 
137 hme0: flags=2000841<UP,RUNNING,MULTICAST,IPv6> mtu 1500 index 2
138         ether 8:0:20:8d:38:c1 
139         inet6 fe80::a00:20ff:fe8d:38c1/10 
140 hme0:1: flags=2080841<UP,RUNNING,MULTICAST,ADDRCONF,IPv6> mtu 1500 index 2
141         inet6 fec0::56:a00:20ff:fe8d:38c1/64 
142 hme0:2: flags=2080841<UP,RUNNING,MULTICAST,ADDRCONF,IPv6> mtu 1500 index 2
143         inet6 2000::56:a00:20ff:fe8d:38c1/64 
144 hme0:3: flags=2080841<UP,RUNNING,MULTICAST,ADDRCONF,IPv6> mtu 1500 index 2
145         inet6 2::56:a00:20ff:fe8d:38c1/64 
146 ppp0: flags=10008d1<UP,POINTOPOINT,RUNNING,NOARP,MULTICAST,IPv4> mtu 1500 index 12
147         inet 172.16.1.1 --> 172.16.1.2 netmask ffffff00 
148 ppp0: flags=2202851<UP,POINTOPOINT,RUNNING,MULTICAST,UNNUMBERED,NONUD,IPv6> mtu 1500 index 12
149         inet6 fe80::a00:20ff:fe8d:38c1/10 --> fe80::a00:20ff:fe7a:24fb
150
151 Note also that a plumbed ipv6 interface stream will exist throughout
152 the entire PPP session in the case where the peer rejects IPV6CP,
153 which further causes the interface state to stay down. Unplumbing will
154 happen when the daemon exits. This is done by design and is not a bug.
155
156 64-bit Support.
157 ***************
158
159 This version has been tested under Solaris 7 (and Solaris 8 ) in both
160 32- and 64-bits environments (Ultra class machines).  Installing the
161 package by executing "make install" will result in additional files
162 residing in /kernel/drv/sparcv9 and /kernel/strmod/sparcv9
163 subdirectories.
164
165 64-bit modules and driver have been compiled and tested using Sun's cc.
166
167 Synchronous Serial Support.
168 ***************************
169
170 This version has working but limited support for the on-board
171 synchronous HDLC interfaces. It has been tested with the /dev/se_hdlc
172 and /dev/zsh drivers.  Synchronous mode was tested with a Cisco
173 router.
174
175 There ppp daemon does not directly support controlling the serial
176 interface.  It relies on the /usr/sbin/syncinit command to initialize
177 HDLC mode and clocking.
178
179 Some bugs remain: large sized frames are not sent/received properly,
180 and may be related to the IP mtu.  This may be due to bugs in pppd
181 itself, bugs in Solaris or the serial drivers.  The /dev/zsh driver
182 seems more larger and can send/receive larger frames than the
183 /dev/se_hdlc driver. There is a confirmed bug with NRZ/NRZI mode in
184 the /dev/se_hdlc driver, and Solaris patch 104596-11 is needed to
185 correct it. (However this patch seems to introduce other serial
186 problems. If you don't apply the patch, the workaround is to change
187 the nrzi mode to yes or no, whichever works)
188
189 How to start pppd with synchronous support:
190
191 #!/bin/sh
192
193 local=1.1.1.1   # your ip address here
194 baud=38400      # needed, but ignored by serial driver
195
196 # Change to the correct serial driver/port
197 #dev=/dev/zsh0
198 dev=/dev/se_hdlc0
199  
200 # Change the driver, nrzi mode, speed and clocking to match your setup
201 # This configuration is for external clocking from the DCE
202 connect="syncinit se_hdlc0 nrzi=no speed=64000 txc=rxc rxc=rxc"
203  
204 /usr/sbin/pppd $dev sync $baud novj noauth $local: connect "$connect"
205
206
207 Sample Cisco router config excerpt:
208
209 !
210 ! Cisco router setup as DCE with RS-232 DCE cable
211
212 !         
213 interface Serial0
214  ip address 1.1.1.2 255.255.255.0
215  encapsulation ppp
216  clockrate 64000
217  no nrzi-encoding
218  no shutdown
219 !         
220