1 \input texinfo @c -*-texinfo-*-
3 @c $Id: unet.texi,v 1.2 2001/02/03 18:39:59 mdw Exp $
5 @c Manual for usernet device
7 @c (c) 1998 Mark Wooding
10 @c ----- Revision history ---------------------------------------------------
12 @c $Log: unet.texi,v $
13 @c Revision 1.2 2001/02/03 18:39:59 mdw
14 @c Setting the maximum interface count now does the right thing.
16 @c Revision 1.1 2001/01/25 22:03:39 mdw
17 @c Initial check-in (somewhat belated).
20 @c ----- Standard boilerplate -----------------------------------------------
23 @setfilename unet.info
24 @settitle The Linux Usernet network interface
25 @setchapternewpage odd
35 @c ----- Useful macros ------------------------------------------------------
39 @c ----- Copyright matters --------------------------------------------------
41 @c --- The `Info' version ---
45 This file documents the Linux Usernet network interface version
48 Copyright (c) 1998 Mark Wooding
50 Permission is granted to make and distribute verbatim copies of this
51 manual provided the copyright notice and this permission notice are
52 preserved on all copies.
55 Permission is granted to process this file through TeX and print the
56 results, provided the printed document carries a copying permission
57 notice identical to this one except for the removal of this paragraph
58 (this paragraph not being relevant to the printed manual).
61 Permission is granted to copy and distribute modified versions of this
62 manual under the conditions for verbatim copying, provided also that the
63 sections entitled `Copying' and `GNU General Public License' are
64 included exactly as in the original, and provided that the entire
65 resulting derived work is distributed under the terms of a permission
66 notice identical to this one.
68 Permission is granted to copy and distribute translations of this manual
69 into another language, under the above conditions for modified versions,
70 except that this permission notice may be stated in a translation
71 approved by the copyright holder.
75 @c --- Printed title page ---
79 @title The Linux Usernet network interface.
80 @subtitle Transmitting Internet Protocol packets from user processes.
81 @author Mark Wooding (@email{mdw@@excessus.demon.co.uk})
84 @vskip 0pt plus 1filll
86 Copyright @copyright{} 1998 Mark Wooding
88 Permission is granted to make and distribute verbatim copies of this
89 manual provided the copyright notice and this permission notice are
90 preserved on all copies.
92 Permission is granted to copy and distribute modified versions of this
93 manual under the conditions for verbatim copying, provided also that the
94 sections entitled `Copying' and `GNU General Public License' are
95 included exactly as in the original, and provided that the entire
96 resulting derived work is distributed under the terms of a permission
97 notice identical to this one.
99 Permission is granted to copy and distribute translations of this manual
100 into another language, under the above conditions for modified versions,
101 except that this permission notice may be stated in a translation
102 approved by the copyright holder.
107 @c --------------------------------------------------------------------------
109 @node Top, Copying, (dir), (dir)
110 @top The Linux Usernet network interface
112 Usernet allows network interfaces to be attached to character devices. Any
113 packets sent through the network interface will be passed to the process
114 reading the device, and data written to the device will appear to have been
115 received from the network interface.
117 This file documents Linux Usernet version @value{version}.
120 * Copying:: You may modify and redistribute Usernet
121 * Introduction:: What Usernet actually does
122 * Technical details:: How Usernet does what it does
123 * Installing:: How to build and install Usernet
124 * Configuring attachments:: The provided configuration program
125 * Programming:: How to program the Usernet kernel module
127 --- The Detailed Node Listing ---
129 Overview and technical details
131 * Attachments:: Attaching devices and network interfaces
132 * Usernet devices:: How Usernet's devices behave
134 Configuring and installing
136 * Autoconfiguring:: How Usernet configures itself
137 * Compiling and installing:: How to compile and install Usernet
139 The @code{unetcfg} program
141 * Invoking unetcfg:: Command line options
142 * Selecting attachments:: Setting the current attachment
143 * Attachment status:: Querying current status information
144 * Protocol settings:: Setting the protocol for outgoing packets
145 * Setting debugging options:: Various debugging settings
149 * Opening and closing:: Opening and closing attachments
150 * Configuring the interface:: How to configure an attached interface
151 * Sending and receiving:: Sending and receiving network packets
157 @c --------------------------------------------------------------------------
158 @node Copying, Introduction, Top, Top
159 @unnumbered The GNU General Public License
164 @c --------------------------------------------------------------------------
165 @node Introduction, Technical details, Copying, Top
166 @unnumbered Introduction
168 Access to Linux's networking tends to be fairly high-level. A user process
169 can send and receive datagrams, or set up connections to other processes
170 easily enough. Privileged processes can build arbitrary IP packets and send
171 them, although raw IP sockets only receive packets for protocols unrecognised
172 by the kernel. Getting hold of all packets sent to a particular host is
173 rather more difficult, though. However, this can be a useful thing to want
174 to do. Usernet is a small kernel module which enables user processes to
175 attach to a network interface and read and write packets to it.
177 Usernet works by creating pairs of character devices and network interfaces.
178 Any packet Linux sends to the network interface is sent unchanged to the
179 process reading the character device; similarly, when a block of data is
180 written to the character device, Usernet claims that it was received from the
181 corresponding network interface.
183 The @samp{diald} program needs to be able to trap packets sent along a
184 particular route to know when to open a dialup connection. The current
185 implementation sets up a SLIP interface on a pseudoterminal, which is kludgy
186 at best. It could be modified to use a Usernet interface, and read and write
189 The application which motivated the writing of Usernet was setting up a
190 virtual private network (VPN). Each end could set up a point-to-point
191 Usernet interface, and run a fairly small daemon, which would read packets
192 sent to the remote end, encrypt them and retransmit them as IP-in-IP
193 encapsulated datagrams, and decrypt any received IP-in-IP datagrams and
194 reinsert them through the Usernet interface.
197 @c --------------------------------------------------------------------------
198 @node Technical details, Installing, Introduction, Top
199 @chapter Overview and technical details
201 This chapter explains in more detail how Usernet is arranged and how it
205 * Attachments:: Attaching devices and network interfaces
206 * Usernet devices:: How Usernet's devices behave
210 @node Attachments, Usernet devices, Technical details, Technical details
213 The Usernet kernel module creates @dfn{attachments} between character devices
214 and network interfaces. Any packet sent by the kernel through the network
215 interface can be read from the character device. Any buffers sent to the
216 device will appear to have been received by the attached interface.
218 The Usernet module understands two types of attachments:
222 @dfn{Persistent attachments} between character devices with low minor device
223 numbers are initialised when the module is loaded. The network interfaces
224 always exist, and can be configured at boot time if the module is loaded
228 @dfn{Transient attachments} are set up dynamically when a process opens a
229 Usernet device with no preattached interface. The network interface is
230 created when the device is opened, and destroyed again when the device is
231 closed. Each open of the device creates a @emph{separate} attachment, so you
232 only need one device for any number of transient attachments.
235 Usernet imposes a limitation on the number of attachments, mainly to stop
236 runaway processes from gobbling kernel resources; there aren't any
237 pre-allocated tables which would prevent you from hiking this parameter
238 upwards if you had a reason to.
241 @node Usernet devices, , Attachments, Technical details
242 @section Usernet devices
244 Usernet claims a major device number (chosen at configuration time:
247 The lowest numbered minor devices are persistently
248 attached to network interfaces: the network device @code{unet@var{n}} is
249 attached to minor device @var{n}, conventionally named
250 @code{/dev/unet@var{n}}.
252 If a device is opened for which there is no persistent attachment, a new
253 network interface is allocated and a transient attachment is made. Each
254 separate @code{open}(2) call creates a new network interface and attachment,
255 which are destroyed again when the file descriptor on the device is closed.
256 It's normal to have one device with no persistent attachment, named
260 @c --------------------------------------------------------------------------
261 @node Installing, Configuring attachments, Technical details, Top
262 @chapter Configuring and installing
264 Usernet is meant to be both simple to set up for most people, and
265 sufficiently flexible to meet more advanced needs.
268 * Autoconfiguring:: How Usernet configures itself
269 * Compiling and installing:: How to compile and install Usernet
273 @node Autoconfiguring, Compiling and installing, Installing, Installing
274 @section Configuration options
276 Configuration is performed using GNU Autoconf. Running the supplied
277 @code{configure} script without any options will configure Usernet to compile
278 properly under most Linux systems.
280 The standard options accepted by Autoconf-generated configure scripts are
281 described in @ref{Invoking configure, , Running @code{configure} Scripts,
282 autoconf, Creating Automatic Configuration Scripts}. In addition to the
283 standard Autoconf options, Usernet's script understands these:
286 @item --with-linux-source=@var{dir}
287 Informs the configuration script that the Linux kernel sources are available
288 in directory @var{dir}. The configuration script will find your source code
289 in most sane installations.
291 @item --with-module-dir=@var{dir}
292 Informs the configuration script that the compiled kernel module is to be
293 installed in directory @var{dir}. The configuration script will find
294 somewhere sensible in most sane installations.
296 @item --with-major-device=@var{num}
297 Sets the major device of all Usernet character devices to @var{num}. Only
298 change this if you find that Usernet is conflicting with some other device.
300 @item --with-persistent-devices=@var{num}
301 Sets the number of persistent attachment devices created by Usernet when it's
302 loaded to @var{num}. The default is 1.
304 @item --with-transient-minor=@var{num}
305 Sets the minor device number of the device special file @code{/dev/unet},
306 used to create transient attachments, to @var{num}. The default is 256; you
307 only need to change this if you've created a lot of persistent devices.
309 @item --with-max-queue-length=@var{num}
310 Sets the maximum number of packets Usernet will queue for the process reading
311 from an attached character device to @var{num}. You probably don't need to
314 @item --with-max-interfaces=@var{num}
315 Sets the maximum number of attached network interfaces Usernet will allow to
316 exist at any given time to @var{num}. The default is fairly generous, so you
317 shouldn't need to play with this unless you're doing something rather
320 @item --with-debugging
321 Enables profuse logging of things Usernet is doing, including complete hex
322 dumps of all the network packets the module processes.
326 @node Compiling and installing, , Autoconfiguring, Installing
327 @section Compiling and installing
329 Once Usernet has been autoconfigured, you should be able to type
339 and the module will compile and install.
341 You'll need to create the character devices to allow processes to talk to
342 Userdev. The script @code{makedev.unet} will create the appropriate
343 devices. Run without any options, it will create devices appropriate to the
344 configuration passed to @code{configure}. Type
349 for information about the options it supports: they're not particularly
350 useful if you got the configuration right.
352 If you later change your configuration, run @code{makedev.unet} again and it
353 will set everything straight.
356 @c --------------------------------------------------------------------------
357 @node Configuring attachments, Programming, Installing, Top
358 @chapter The @code{unetcfg} program
361 A Usernet attachment can be interrogated and configured using the
362 @code{unetcfg} program supplied.
365 * Invoking unetcfg:: Command line options
366 * Selecting attachments:: Setting the current attachment
367 * Attachment status:: Querying current status information
368 * Protocol settings:: Setting the protocol for outgoing packets
369 * Setting debugging options:: Various debugging settings
373 @node Invoking unetcfg, Selecting attachments, Configuring attachments, Configuring attachments
374 @section Invoking @code{unetcfg}
376 The @code{unetcfg} program is called as:
378 unetcfg [@var{option}@dots{}] @var{command}@dots{}
381 The various @var{option}s supported are as follows:
386 Displays a helpful and informative summary of @code{unetcfg}'s option
391 Displays the version number of your copy of @code{unetcfg}.
395 Enables output of largely useless status messages. These might be of use
396 when @code{unetcfg} doesn't seem to be doing what you want it to.
400 Each @var{command} is executed in turn, from left to right. The command
401 namees may be abbreviated, as long as the abbreviation is not ambiguous.
403 Most of the commands work with a @dfn{current attachment}, which is assumed
404 to be standard input by default. The current attachment may be changed using
405 the @code{select} and @code{fd} commands (@pxref{Selecting attachments}).
408 @node Selecting attachments, Attachment status, Invoking unetcfg, Configuring attachments
409 @section Changing the current attachment
411 These commands change the current attachment. You can use them as often as
412 you like in a single invocation of @code{unetcfg}.
414 @deffn Command select @var{filename}
415 Selects @var{filename} as the current attachment. Further operations will be
416 performed on the named device.
418 The command name @code{select} is optional: an argument which isn't a command
419 name is assumed to be a filename to select.
422 @deffn Command fd @var{filedesc}
423 Selects an open file descriptor to be the current attachment. As well as
424 boring old file descriptor numbers, you can use the names @code{stdin},
425 @code{stdout} and @code{stderr}.
427 Note that it's really silly to set the current attachment to be standard
428 output and then perform commands which write to stdout:
430 unetcfg fd stdout show
437 @node Attachment status, Protocol settings, Selecting attachments, Configuring attachments
438 @section Attachment status
440 These commands write useful information about the current attachment to
444 Writes information about the current attachment to standard output. The
445 format of the information is not intended to be processed by other programs,
446 and may vary between releases of the software.
449 @deffn Command ifname
450 Writes the name of the currently attached network interface to standard
451 error. This can be useful in configuration scripts. For example:
453 ifname=`unetcfg fd 3 ifname`
454 ifconfig $ifname localend pointopoint remoteend
458 @node Protocol settings, Setting debugging options, Attachment status, Configuring attachments
459 @section Protocol settings
461 Each packet received by a network interface must have a protocol stamped on
462 it. Packets injected by writing to a Usernet-attached device are stamped
463 with the attachment's current protocol. The following command allows the
464 current attachment's protocol to be set.
466 @deffn Command protocol @var{proto}
467 Sets the protocol stamped on packets injected through the current
468 attachment. A list of currently known protocols may be obtained by
469 specifying the special protocol name @code{help}. The default protocol is
474 @node Setting debugging options, , Protocol settings, Configuring attachments
475 @section Setting debugging options
479 @deffn Command help [@var{command}]
480 With no arguments, displays a summary of the commands available. With a
481 @var{command} argument, displays help on that command.
485 @c --------------------------------------------------------------------------
486 @node Programming, , Configuring attachments, Top
487 @chapter Programming Usernet
489 This chapter documents Usernet's programming interface. It's not
490 particularly complicated, you'll be glad to hear.
493 * Opening and closing:: Opening and closing attachments
494 * Configuring the interface:: How to configure an attached interface
495 * Sending and receiving:: Sending and receiving network packets
499 @node Opening and closing, Configuring the interface, Programming, Programming
500 @section Opening and closing
502 Opening and closing Usernet devices is simple and obvious. Calling
503 @code{open}(2) on the appropriate special file opens the device. What
504 happens now depends on whether the device has a persistent attachment to a
508 @item If the device has a persistent attachment, a check is made to see
509 whether the device has already been opened by another process. If this is
510 the case, @code{open} returns @code{EBUSY}. If the device was not already
511 opened, it is marked as open and a file descriptor is returned.
513 @item If the device does not have a persistent attachment, a fresh network
514 interface is allocated and attached to the device. A file descriptor for the
515 opened device is returned.
518 Closing a transiently attached device will release and destroy the attached
522 @node Configuring the interface, Sending and receiving, Opening and closing, Programming
523 @section Configuring the interface
525 Usernet interfaces can be configured using some simple @code{ioctl}(2) calls
526 supported by the Usernet character devices. The constants and data
527 structures required are defined in the header file @file{unet.h} provided in
530 Most of the configuration work is performed on the network interface, and
531 this is done using the traditional @code{ioctl} calls on an open socket's
534 The following @code{ioctl} calls are provided for configuring Usernet
537 @deffn {@code{ioctl} call} UNIOCGINFO
538 Returns the a summary of the attachment's current configuration. The
539 argument is a pointer to a structure of type @code{struct
540 unet_info}, which contains the following members:
543 @item char uni_ifname[UNET_NAMEMAX];
544 Interface name string. This may be passed to the @code{ifconfig} program, or
545 to the interface configuration @code{ioctl} calls to configure the attached
548 @item unsigned short uni_mtu;
549 Maximum transmission unit of the attached interface. This is also available
550 by calling @code{SIOCGIFMTU}, and may be set by calling @code{SIOCSIFMTU}.
552 @item unsigned short uni_family;
553 Address family of the attached interface. This is usually @code{AF_UNIX},
554 although it may be changed by calling @code{SIOCSIFADDR}.
556 @item unsigned short uni_proto;
557 Network protocol number stamped onto packets to be sent from the attached
558 network interface. The default, which is probably good enough, is
559 @code{ETH_P_IP}. This field may be changed by calling @code{UNIOCSPROTO}.
561 @item unsigned int uni_flags;
562 An inclusive-OR of the following possible values:
565 Attachment is transient.
567 Currently always set. Ignore this bit.
569 Debugging enabled on this interface.
576 struct unet_info uni;
577 int fd = open("/dev/unet", O_RDWR);
579 die("couldn't open /dev/unet: %s", strerror(errno));
580 if (ioctl(fd, UNIOCGINFO, &uni) < 0)
581 die("couldn't get config information: %s", strerror(errno));
582 printf("interface name = `%s'\n", uni.uni_ifname);
587 @deffn {@code{ioctl} call} UNIOCSDEBUG
588 Sets or clears the debug state for a Usernet attachment. If the argument is
589 nonzero, the debug flag is set; if zero, the flag is cleared. When debugging
590 is enabled for an attachment, Usernet logs packets sent and received through
591 it, and most changes to the attachment's state, to the kernel log.
594 @deffn {@code{ioctl} call} UNIOCGPROTO
595 Reads the protocol number stamped onto packets submitted by an attached
596 Usernet interface. The value returned by the @code{ioctl} call is identical
597 to the @code{uni_proto} member returned by @code{UNIOCGINFO}.
600 @deffn {@code{ioctl} call} UNIOCSPROTO
601 Sets the protocl number stamped onto outgoing packets. The protocol number,
602 passed as the @code{ioctl}'s argument, must be one of the constants defined
603 in @file{linux/if_ether.h}.
606 @deffn {@code{ioctl} call} UNIOCGGDEBUG
607 Reads the global debug flag. When global debugging is enabled, all newly
608 created attachments have debugging turned on automatically, and various
609 global events are logged to the kernel log.
612 @deffn {@code{ioctl} call} UNIOCSGDEBUG
613 Sets the global debug flag; if the argument is nonzero, the global debug flag
614 is set; if zero, the flag is cleared.
617 @deffn {@code{ioctl} call} UNIOCDUMP
618 Dumps an attachment's information to the kernel log device.
621 @deffn {@code{ioctl} call} UNIOCGMAXIF
622 Returns the total number of attachments permitted.
625 @deffn {@code{ioctl} call} UNIOCSMAXIF
626 Configures the total number of attachments permitted. It is an error to
627 reduce this below the number of attachments currently in existence.
631 @node Sending and receiving, , Configuring the interface, Programming
632 @section Sending and receiving
634 A packet may be sent through a Usernet interface using the standard
635 @code{write}(2) system call. The buffer passed to @code{write} must be a
636 complete packet; no coalescing or buffering is performed by Usernet. It's
637 always possible to write to a Usernet device and writing always succeeds
638 without blocking. However, packets may be silently rejected by the network
641 Packets received by a Usernet interface are available to programs via the
642 standard @code{read}(2) system call. If the destination buffer is too small
643 for a complete packet, the remainder of the packet is silently discarded. If
644 no packets are available for reading, the process is blocked (unless
645 nonblocking I/O was explicitly requested).
647 Programs may call @code{select}(2) to wait for packets to arrive from an
648 attached Usernet device.
651 @c @node Hints, , Sending and receiving, Programming
654 @c --------------------------------------------------------------------------