Luigi Rizzo's pointers: email: rizzo@iet.unipi.it [home] [research] [NGC99 workshop]

A PGM Host Implementation for FreeBSD

Here you can find source code and documentation for a PGM Host implementation for various releases of FreeBSD. If you use this code, I'd be grateful if you could send feedback, and report any bugs you should find.

The code is very stable, and i have it running on several of our systems including my own workstation since fall'99. However, the usual disclaimer applies - use this code at your own risk!

The most recent version (released 11 february 2000) has the following features:

These features make it possible to use PGM sockets much like TCP. A simple test application, pgmcat is also available which lets you do a simple reliable multicast file transfer, with full congestion control, by running: 
    pgmcat -s -ttl TTL group/port < source_file   # on the sender

    pgmcat group/port > dest_file   # on the receivers.

NS Code for simulations

The following tgz archive contains a number of patchfiles which must be used with the FreeBSD port of NS 2.1.5 to run simulations of the PGMCC congestion control scheme.

You should be able to put them into /usr/ports/net/ns/patches and use "make" to rebuild NS If you want to apply the patches manually, here is the content of the files: 

 aa      - ...
 ba      - Makefile changes
 ca..ch  - PGM stuff (sender, receiver and network element)
 da..db  - pgmcc stuff
 ea..ef  - network element changes
 fa..fd  - changes related to xplot and tcp

1. Getting and installing source code.

To get the latest version, use the URL http://www.iet.unipi.it/~luigi/pgm-code/ . The naming convention for the files is something like 
    kpgm-991009.tgz
    sample-991009.tgz
    doc-991009.tgz
respectively for kernel source, sample code and documentation (none at the moment!). Should some archive be specific for a particular version of the operating system, the OS name/release is included in the filename.

The kpgm archive generally contains a patchfile to update a few kernel files, the four new files containing the full PGM host implementation, and basic documentation (install instructions, manual page, code architecture).

The new files are 

    /usr/src/sys/netinet/pgm.h
    /usr/src/sys/netinet/pgm_var.h
    /usr/src/sys/netinet/pgm_timer.c
    /usr/src/sys/netinet/pgm_usrreq.c
    /usr/src/sys/netinet/pgm.4
whereas the patchfile (there are a few different versions depending on the OS release you are using) updates at most the following files 
    /usr/src/sys/netinet/in.h
    /usr/src/sys/netinet/in_proto.c
    /usr/src/sys/conf/files
    /usr/src/sys/conf/options
The patches merely provide the glue to recognize the new files and include them in the kernel compile, so they are not going to change over time. You are encouraged to have a look at them to verify that they are "safe".

While the PGM implementation is experimental, the kernel build process is totally unaffected if you don't have "options PGM" in your kernel configuration file -- in other words, don't be afraid of destroying your system's sources.

To install this code, read the detailed instructions in the INSTALL file part of the kpgm archive -- the install process is as simple as running patch, copying the new files to their locations, and build a new kernel which includes the line options PGM in the kernel configuration file.

2. Testing the code and running applications.

To test the code, your best approach is to compile the sample application(s), e.g. pgmcat. You can run multiple receivers on the same machine as the sender, or distribute them over different machines on the net.

Check the pgm(4) manpage for a detailed description of the socket API and of sysctl variables which let you set PGM operating parameters. To test the recovery process, it is very convenient to use a standard piece of FreeBSD called dummynet, a flexible bandwidth manager/delay emulator/link emulator (another one of my babies...).
To include dummynet in your kernel you have to include just a few options in your kernel config file, then you can write things like this 

    ipfw add pipe 1 113 from any to any in
    ipfw add pipe 2 113 from any to any out
    ipfw pipe 1 config bw 100Kbit/s queue 20 delay 300ms plr 0.4
    ipfw pipe 2 config bw 120Kbit/s queue 20 delay 100ms plr 0.1
(where 113 is the protocol number associated with PGM). This specific example will route inbound and outbound PGM traffic to two different pipes whose parameters are shown in the configuration line.

3. A demo version.

For those who want to try PGM without having to install FreeBSD or patch their system, I provide a floppy image of a system with FreeBSD, PGM, pgmcat, and test tools such as ipfw, dummynet, tcpdump.
The disk has drivers for a few interfaces, and accessible via telnet.

To setup this system, download the 1.44MB image, picopgm.000216.bin and copy it to a floppy using dd under FreeBSD, or rawrite under DOS/Windows.

Then put the floppy into a machine with hopefully at least one ethernet interface, and wait for it to boot. When the system comes up, it will ask for the hostname and ip for the machine. After that you can login as root, password "setup" and you can run pgmcat, dummynet etc.

Acknowledgements

This work has been partly sponsored by Cisco Systems, Microsoft Research, and by the italian MURST under project Mosaico.

Simone Bertoni, Lorenzo Conti and Gianluca Iannaccone have helped writing and testing this code. Gianluca and Valentina Benucci are the main authors of the NS code.

DISCLAIMER: use this code at your own risk. This is experimental code. It does not implement 100% of the PGM spec. It is not guaranteed for stability, and you should not be surprised if your machine crashes while using it.
The fact that I haven't managed to panic my system with this code does not mean it cannot happen in a million different ways.