Initial check-in (somewhat belated).

[unet] / unet.texi

\input texinfo @c -*-texinfo-*-
@c
@c $Id: unet.texi,v 1.1 2001/01/25 22:03:39 mdw Exp $
@c
@c Manual for usernet device
@c
@c (c) 1998 Mark Wooding
@c

@c ----- Revision history ---------------------------------------------------
@c
@c $Log: unet.texi,v $
@c Revision 1.1  2001/01/25 22:03:39  mdw
@c Initial check-in (somewhat belated).
@c

@c ----- Standard boilerplate -----------------------------------------------

@c %**start of header
@setfilename unet.info
@settitle The Linux Usernet network interface
@setchapternewpage odd
@footnotestyle end
@paragraphindent 0
@iftex
@input texinice
@afourpaper
@c @parindent=0pt
@end iftex
@c %**end of header

@c ----- Useful macros ------------------------------------------------------

@set version 1.1

@c ----- Copyright matters --------------------------------------------------

@c --- The `Info' version ---

@ifinfo

This file documents the Linux Usernet network interface version
@value{version}. 

Copyright (c) 1998 Mark Wooding

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled `Copying' and `GNU General Public License' are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the copyright holder.

@end ifinfo

@c --- Printed title page ---

@titlepage

@title The Linux Usernet network interface.
@subtitle Transmitting Internet Protocol packets from user processes.
@author Mark Wooding (@email{mdw@@excessus.demon.co.uk})
@page

@vskip 0pt plus 1filll

Copyright @copyright{} 1998 Mark Wooding

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled `Copying' and `GNU General Public License' are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the copyright holder.

@end titlepage


@c --------------------------------------------------------------------------
@ifinfo
@node Top, Copying, (dir), (dir)
@top The Linux Usernet network interface

Usernet allows network interfaces to be attached to character devices.  Any
packets sent through the network interface will be passed to the process
reading the device, and data written to the device will appear to have been
received from the network interface.

This file documents Linux Usernet version @value{version}.

@menu
* Copying::                     You may modify and redistribute Usernet
* Introduction::                What Usernet actually does
* Technical details::           How Usernet does what it does
* Installing::                  How to build and install Usernet
* Configuring attachments::     The provided configuration program
* Programming::                 How to program the Usernet kernel module

 --- The Detailed Node Listing ---

Overview and technical details

* Attachments::                 Attaching devices and network interfaces
* Usernet devices::             How Usernet's devices behave

Configuring and installing

* Autoconfiguring::             How Usernet configures itself
* Compiling and installing::    How to compile and install Usernet

The @code{unetcfg} program

* Invoking unetcfg::            Command line options
* Selecting attachments::       Setting the current attachment
* Attachment status::           Querying current status information
* Protocol settings::           Setting the protocol for outgoing packets
* Setting debugging options::   Various debugging settings

Programming Usernet

* Opening and closing::         Opening and closing attachments
* Configuring the interface::   How to configure an attached interface
* Sending and receiving::       Sending and receiving network packets
@end menu

@end ifinfo


@c --------------------------------------------------------------------------
@node Copying, Introduction, Top, Top
@unnumbered The GNU General Public License

@include gpl.texi


@c --------------------------------------------------------------------------
@node Introduction, Technical details, Copying, Top
@unnumbered Introduction

Access to Linux's networking tends to be fairly high-level.  A user process
can send and receive datagrams, or set up connections to other processes
easily enough.  Privileged processes can build arbitrary IP packets and send
them, although raw IP sockets only receive packets for protocols unrecognised
by the kernel.  Getting hold of all packets sent to a particular host is
rather more difficult, though.  However, this can be a useful thing to want
to do.  Usernet is a small kernel module which enables user processes to
attach to a network interface and read and write packets to it.

Usernet works by creating pairs of character devices and network interfaces.
Any packet Linux sends to the network interface is sent unchanged to the
process reading the character device; similarly, when a block of data is
written to the character device, Usernet claims that it was received from the
corresponding network interface.

The @samp{diald} program needs to be able to trap packets sent along a
particular route to know when to open a dialup connection.  The current
implementation sets up a SLIP interface on a pseudoterminal, which is kludgy
at best.  It could be modified to use a Usernet interface, and read and write
packets from there.

The application which motivated the writing of Usernet was setting up a
virtual private network (VPN).  Each end could set up a point-to-point
Usernet interface, and run a fairly small daemon, which would read packets
sent to the remote end, encrypt them and retransmit them as IP-in-IP
encapsulated datagrams, and decrypt any received IP-in-IP datagrams and
reinsert them through the Usernet interface.


@c --------------------------------------------------------------------------
@node Technical details, Installing, Introduction, Top
@chapter Overview and technical details

This chapter explains in more detail how Usernet is arranged and how it
works.

@menu
* Attachments::                 Attaching devices and network interfaces
* Usernet devices::             How Usernet's devices behave
@end menu


@node Attachments, Usernet devices, Technical details, Technical details
@section Attachments

The Usernet kernel module creates @dfn{attachments} between character devices
and network interfaces.  Any packet sent by the kernel through the network
interface can be read from the character device.  Any buffers sent to the
device will appear to have been received by the attached interface.

The Usernet module understands two types of attachments:

@itemize @bullet
@item
@dfn{Persistent attachments} between character devices with low minor device
numbers are initialised when the module is loaded.  The network interfaces
always exist, and can be configured at boot time if the module is loaded
early enough.

@item
@dfn{Transient attachments} are set up dynamically when a process opens a
Usernet device with no preattached interface.  The network interface is
created when the device is opened, and destroyed again when the device is
closed.  Each open of the device creates a @emph{separate} attachment, so you
only need one device for any number of transient attachments.
@end itemize

Usernet imposes a limitation on the number of attachments, mainly to stop
runaway processes from gobbling kernel resources; there aren't any
pre-allocated tables which would prevent you from hiking this parameter
upwards if you had a reason to.


@node Usernet devices,  , Attachments, Technical details
@section Usernet devices

Usernet claims a major device number (chosen at configuration time:
@xref{Installing}).

The lowest numbered minor devices are persistently
attached to network interfaces: the network device @code{unet@var{n}} is
attached to minor device @var{n}, conventionally named
@code{/dev/unet@var{n}}.

If a device is opened for which there is no persistent attachment, a new
network interface is allocated and a transient attachment is made.  Each
separate @code{open}(2) call creates a new network interface and attachment,
which are destroyed again when the file descriptor on the device is closed.
It's normal to have one device with no persistent attachment, named
@code{/dev/unet}.


@c --------------------------------------------------------------------------
@node Installing, Configuring attachments, Technical details, Top
@chapter Configuring and installing

Usernet is meant to be both simple to set up for most people, and
sufficiently flexible to meet more advanced needs.

@menu
* Autoconfiguring::             How Usernet configures itself
* Compiling and installing::    How to compile and install Usernet
@end menu


@node Autoconfiguring, Compiling and installing, Installing, Installing
@section Configuration options

Configuration is performed using GNU Autoconf.  Running the supplied
@code{configure} script without any options will configure Usernet to compile
properly under most Linux systems.

The standard options accepted by Autoconf-generated configure scripts are
described in @ref{Invoking configure, , Running @code{configure} Scripts,
autoconf, Creating Automatic Configuration Scripts}.  In addition to the
standard Autoconf options, Usernet's script understands these:

@table @code
@item --with-linux-source=@var{dir}
Informs the configuration script that the Linux kernel sources are available
in directory @var{dir}.  The configuration script will find your source code
in most sane installations.

@item --with-module-dir=@var{dir}
Informs the configuration script that the compiled kernel module is to be
installed in directory @var{dir}.  The configuration script will find
somewhere sensible in most sane installations.

@item --with-major-device=@var{num}
Sets the major device of all Usernet character devices to @var{num}.  Only
change this if you find that Usernet is conflicting with some other device.

@item --with-persistent-devices=@var{num}
Sets the number of persistent attachment devices created by Usernet when it's
loaded to @var{num}.  The default is 1.

@item --with-transient-minor=@var{num}
Sets the minor device number of the device special file @code{/dev/unet},
used to create transient attachments, to @var{num}.  The default is 256; you
only need to change this if you've created a lot of persistent devices.

@item --with-max-queue-length=@var{num}
Sets the maximum number of packets Usernet will queue for the process reading
from an attached character device to @var{num}.  You probably don't need to
fiddle with this.

@item --with-max-interfaces=@var{num}
Sets the maximum number of attached network interfaces Usernet will allow to
exist at any given time to @var{num}.  The default is fairly generous, so you
shouldn't need to play with this unless you're doing something rather
strange.

@item --with-debugging
Enables profuse logging of things Usernet is doing, including complete hex
dumps of all the network packets the module processes.
@end table


@node Compiling and installing,  , Autoconfiguring, Installing
@section Compiling and installing

Once Usernet has been autoconfigured, you should be able to type
@example
$ make
...
$ su root
Password: 
# make install
...
@end example
@noindent
and the module will compile and install.

You'll need to create the character devices to allow processes to talk to
Userdev.  The script @code{makedev.unet} will create the appropriate
devices.  Run without any options, it will create devices appropriate to the
configuration passed to @code{configure}.  Type
@example
makedev.unet --help
@end example
@noindent
for information about the options it supports: they're not particularly
useful if you got the configuration right.

If you later change your configuration, run @code{makedev.unet} again and it
will set everything straight.


@c --------------------------------------------------------------------------
@node Configuring attachments, Programming, Installing, Top
@chapter The @code{unetcfg} program


A Usernet attachment can be interrogated and configured using the
@code{unetcfg} program supplied.

@menu
* Invoking unetcfg::            Command line options
* Selecting attachments::       Setting the current attachment
* Attachment status::           Querying current status information
* Protocol settings::           Setting the protocol for outgoing packets
* Setting debugging options::   Various debugging settings
@end menu


@node Invoking unetcfg, Selecting attachments, Configuring attachments, Configuring attachments
@section Invoking @code{unetcfg}

The @code{unetcfg} program is called as:
@example
unetcfg [@var{option}@dots{}] @var{command}@dots{}
@end example

The various @var{option}s supported are as follows:
@table @samp

@item -h
@itemx --help
Displays a helpful and informative summary of @code{unetcfg}'s option
syntax.

@item -V
@itemx --version
Displays the version number of your copy of @code{unetcfg}.

@item -v
@itemx --verbose
Enables output of largely useless status messages.  These might be of use
when @code{unetcfg} doesn't seem to be doing what you want it to.

@end table

Each @var{command} is executed in turn, from left to right.  The command
namees may be abbreviated, as long as the abbreviation is not ambiguous.

Most of the commands work with a @dfn{current attachment}, which is assumed
to be standard input by default.  The current attachment may be changed using
the @code{select} and @code{fd} commands (@pxref{Selecting attachments}).


@node Selecting attachments, Attachment status, Invoking unetcfg, Configuring attachments
@section Changing the current attachment

These commands change the current attachment.  You can use them as often as
you like in a single invocation of @code{unetcfg}.

@deffn Command select @var{filename}
Selects @var{filename} as the current attachment.  Further operations will be
performed on the named device.

The command name @code{select} is optional: an argument which isn't a command
name is assumed to be a filename to select.
@end deffn

@deffn Command fd @var{filedesc}
Selects an open file descriptor to be the current attachment.  As well as
boring old file descriptor numbers, you can use the names @code{stdin},
@code{stdout} and @code{stderr}.

Note that it's really silly to set the current attachment to be standard
output and then perform commands which write to stdout:
@example
unetcfg fd stdout show
@end example
@noindent
Don't do this.
@end deffn


@node Attachment status, Protocol settings, Selecting attachments, Configuring attachments
@section Attachment status

These commands write useful information about the current attachment to
standard output.

@deffn Command show
Writes information about the current attachment to standard output.  The
format of the information is not intended to be processed by other programs,
and may vary between releases of the software.
@end deffn

@deffn Command ifname
Writes the name of the currently attached network interface to standard
error.  This can be useful in configuration scripts.  For example:
@example
ifname=`unetcfg fd 3 ifname`
ifconfig $ifname localend pointopoint remoteend
@end example
@end deffn

@node Protocol settings, Setting debugging options, Attachment status, Configuring attachments
@section Protocol settings

Each packet received by a network interface must have a protocol stamped on
it.  Packets injected by writing to a Usernet-attached device are stamped
with the attachment's current protocol.  The following command allows the
current attachment's protocol to be set.

@deffn Command protocol @var{proto}
Sets the protocol stamped on packets injected through the current
attachment.  A list of currently known protocols may be obtained by
specifying the special protocol name @code{help}.  The default protocol is
always IP.
@end deffn


@node Setting debugging options,  , Protocol settings, Configuring attachments
@section Setting debugging options



@deffn Command help [@var{command}]
With no arguments, displays a summary of the commands available.  With a
@var{command} argument, displays help on that command.
@end deffn


@c --------------------------------------------------------------------------
@node Programming,  , Configuring attachments, Top
@chapter Programming Usernet

This chapter documents Usernet's programming interface.  It's not
particularly complicated, you'll be glad to hear.

@menu
* Opening and closing::         Opening and closing attachments
* Configuring the interface::   How to configure an attached interface
* Sending and receiving::       Sending and receiving network packets
@end menu


@node Opening and closing, Configuring the interface, Programming, Programming
@section Opening and closing

Opening and closing Usernet devices is simple and obvious.  Calling
@code{open}(2) on the appropriate special file opens the device.  What
happens now depends on whether the device has a persistent attachment to a
network interface:

@itemize @bullet
@item If the device has a persistent attachment, a check is made to see
whether the device has already been opened by another process.  If this is
the case, @code{open} returns @code{EBUSY}.  If the device was not already
opened, it is marked as open and a file descriptor is returned.

@item If the device does not have a persistent attachment, a fresh network
interface is allocated and attached to the device.  A file descriptor for the
opened device is returned.
@end itemize

Closing a transiently attached device will release and destroy the attached
network interface.


@node Configuring the interface, Sending and receiving, Opening and closing, Programming
@section Configuring the interface

Usernet interfaces can be configured using some simple @code{ioctl}(2) calls
supported by the Usernet character devices.  The constants and data
structures required are defined in the header file @file{unet.h} provided in
the distribution.

Most of the configuration work is performed on the network interface, and
this is done using the traditional @code{ioctl} calls on an open socket's
file descriptor.

The following @code{ioctl} calls are provided for configuring Usernet
attachments.

@deffn {@code{ioctl} call} UNIOCGINFO
Returns the a summary of the attachment's current configuration.  The
argument is a pointer to a structure of type @code{struct
unet_info}, which contains the following members:
@table @code

@item char uni_ifname[UNET_NAMEMAX];
Interface name string.  This may be passed to the @code{ifconfig} program, or
to the interface configuration @code{ioctl} calls to configure the attached
network interface.

@item unsigned short uni_mtu;
Maximum transmission unit of the attached interface.  This is also available
by calling @code{SIOCGIFMTU}, and may be set by calling @code{SIOCSIFMTU}.

@item unsigned short uni_family;
Address family of the attached interface.  This is usually @code{AF_UNIX},
although it may be changed by calling @code{SIOCSIFADDR}.

@item unsigned short uni_proto;
Network protocol number stamped onto packets to be sent from the attached
network interface.  The default, which is probably good enough, is
@code{ETH_P_IP}.  This field may be changed by calling @code{UNIOCSPROTO}.

@item unsigned int uni_flags;
An inclusive-OR of the following possible values:
@table @code
@item UNIF_TRANS
Attachment is transient.
@item UNIF_OPEN
Currently always set.  Ignore this bit.
@item UNIF_DEBUG
Debugging enabled on this interface.
@end table

@end table

Example:
@example
struct unet_info uni;
int fd = open("/dev/unet", O_RDWR);
if (fd < 0)
  die("couldn't open /dev/unet: %s", strerror(errno));
if (ioctl(fd, UNIOCGINFO, &uni) < 0)
  die("couldn't get config information: %s", strerror(errno));
printf("interface name = `%s'\n", uni.uni_ifname);
@end example

@end deffn

@deffn {@code{ioctl} call} UNIOCSDEBUG
Sets or clears the debug state for a Usernet attachment.  If the argument is
nonzero, the debug flag is set; if zero, the flag is cleared.  When debugging
is enabled for an attachment, Usernet logs packets sent and received through
it, and most changes to the attachment's state, to the kernel log.
@end deffn

@deffn {@code{ioctl} call} UNIOCGPROTO
Reads the protocol number stamped onto packets submitted by an attached
Usernet interface.  The value returned by the @code{ioctl} call is identical
to the @code{uni_proto} member returned by @code{UNIOCGINFO}.
@end deffn

@deffn {@code{ioctl} call} UNIOCSPROTO
Sets the protocl number stamped onto outgoing packets.  The protocol number,
passed as the @code{ioctl}'s argument, must be one of the constants defined
in @file{linux/if_ether.h}.
@end deffn

@deffn {@code{ioctl} call} UNIOCGGDEBUG
Reads the global debug flag.  When global debugging is enabled, all newly
created attachments have debugging turned on automatically, and various
global events are logged to the kernel log.
@end deffn

@deffn {@code{ioctl} call} UNIOCSGDEBUG
Sets the global debug flag; if the argument is nonzero, the global debug flag
is set; if zero, the flag is cleared.
@end deffn

@deffn {@code{ioctl} call} UNIOCDUMP
Dumps an attachment's information to the kernel log device.
@end deffn


@node Sending and receiving,  , Configuring the interface, Programming
@section Sending and receiving

A packet may be sent through a Usernet interface using the standard
@code{write}(2) system call.  The buffer passed to @code{write} must be a
complete packet; no coalescing or buffering is performed by Usernet.  It's
always possible to write to a Usernet device and writing always succeeds
without blocking.  However, packets may be silently rejected by the network
stack.

Packets received by a Usernet interface are available to programs via the
standard @code{read}(2) system call.  If the destination buffer is too small
for a complete packet, the remainder of the packet is silently discarded.  If
no packets are available for reading, the process is blocked (unless
nonblocking I/O was explicitly requested).

Programs may call @code{select}(2) to wait for packets to arrive from an
attached Usernet device.


@c @node Hints,  , Sending and receiving, Programming
@c @section Hints

@c --------------------------------------------------------------------------
@contents
@bye