chiark / gitweb /
Setting the maximum interface count now does the right thing.
[unet] / unet.texi
1 \input texinfo @c -*-texinfo-*-
2 @c
3 @c $Id: unet.texi,v 1.2 2001/02/03 18:39:59 mdw Exp $
4 @c
5 @c Manual for usernet device
6 @c
7 @c (c) 1998 Mark Wooding
8 @c
9
10 @c ----- Revision history ---------------------------------------------------
11 @c
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.
15 @c
16 @c Revision 1.1  2001/01/25 22:03:39  mdw
17 @c Initial check-in (somewhat belated).
18 @c
19
20 @c ----- Standard boilerplate -----------------------------------------------
21
22 @c %**start of header
23 @setfilename unet.info
24 @settitle The Linux Usernet network interface
25 @setchapternewpage odd
26 @footnotestyle end
27 @paragraphindent 0
28 @iftex
29 @input texinice
30 @afourpaper
31 @c @parindent=0pt
32 @end iftex
33 @c %**end of header
34
35 @c ----- Useful macros ------------------------------------------------------
36
37 @set version 1.1
38
39 @c ----- Copyright matters --------------------------------------------------
40
41 @c --- The `Info' version ---
42
43 @ifinfo
44
45 This file documents the Linux Usernet network interface version
46 @value{version}. 
47
48 Copyright (c) 1998 Mark Wooding
49
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.
53
54 @ignore
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).
59
60 @end ignore
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.
67
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.
72
73 @end ifinfo
74
75 @c --- Printed title page ---
76
77 @titlepage
78
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})
82 @page
83
84 @vskip 0pt plus 1filll
85
86 Copyright @copyright{} 1998 Mark Wooding
87
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.
91
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.
98
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.
103
104 @end titlepage
105
106
107 @c --------------------------------------------------------------------------
108 @ifinfo
109 @node Top, Copying, (dir), (dir)
110 @top The Linux Usernet network interface
111
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.
116
117 This file documents Linux Usernet version @value{version}.
118
119 @menu
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
126
127  --- The Detailed Node Listing ---
128
129 Overview and technical details
130
131 * Attachments::                 Attaching devices and network interfaces
132 * Usernet devices::             How Usernet's devices behave
133
134 Configuring and installing
135
136 * Autoconfiguring::             How Usernet configures itself
137 * Compiling and installing::    How to compile and install Usernet
138
139 The @code{unetcfg} program
140
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
146
147 Programming Usernet
148
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
152 @end menu
153
154 @end ifinfo
155
156
157 @c --------------------------------------------------------------------------
158 @node Copying, Introduction, Top, Top
159 @unnumbered The GNU General Public License
160
161 @include gpl.texi
162
163
164 @c --------------------------------------------------------------------------
165 @node Introduction, Technical details, Copying, Top
166 @unnumbered Introduction
167
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.
176
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.
182
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
187 packets from there.
188
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.
195
196
197 @c --------------------------------------------------------------------------
198 @node Technical details, Installing, Introduction, Top
199 @chapter Overview and technical details
200
201 This chapter explains in more detail how Usernet is arranged and how it
202 works.
203
204 @menu
205 * Attachments::                 Attaching devices and network interfaces
206 * Usernet devices::             How Usernet's devices behave
207 @end menu
208
209
210 @node Attachments, Usernet devices, Technical details, Technical details
211 @section Attachments
212
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.
217
218 The Usernet module understands two types of attachments:
219
220 @itemize @bullet
221 @item
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
225 early enough.
226
227 @item
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.
233 @end itemize
234
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.
239
240
241 @node Usernet devices,  , Attachments, Technical details
242 @section Usernet devices
243
244 Usernet claims a major device number (chosen at configuration time:
245 @xref{Installing}).
246
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}}.
251
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
257 @code{/dev/unet}.
258
259
260 @c --------------------------------------------------------------------------
261 @node Installing, Configuring attachments, Technical details, Top
262 @chapter Configuring and installing
263
264 Usernet is meant to be both simple to set up for most people, and
265 sufficiently flexible to meet more advanced needs.
266
267 @menu
268 * Autoconfiguring::             How Usernet configures itself
269 * Compiling and installing::    How to compile and install Usernet
270 @end menu
271
272
273 @node Autoconfiguring, Compiling and installing, Installing, Installing
274 @section Configuration options
275
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.
279
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:
284
285 @table @code
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.
290
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.
295
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.
299
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.
303
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.
308
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
312 fiddle with this.
313
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
318 strange.
319
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.
323 @end table
324
325
326 @node Compiling and installing,  , Autoconfiguring, Installing
327 @section Compiling and installing
328
329 Once Usernet has been autoconfigured, you should be able to type
330 @example
331 $ make
332 ...
333 $ su root
334 Password: 
335 # make install
336 ...
337 @end example
338 @noindent
339 and the module will compile and install.
340
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
345 @example
346 makedev.unet --help
347 @end example
348 @noindent
349 for information about the options it supports: they're not particularly
350 useful if you got the configuration right.
351
352 If you later change your configuration, run @code{makedev.unet} again and it
353 will set everything straight.
354
355
356 @c --------------------------------------------------------------------------
357 @node Configuring attachments, Programming, Installing, Top
358 @chapter The @code{unetcfg} program
359
360
361 A Usernet attachment can be interrogated and configured using the
362 @code{unetcfg} program supplied.
363
364 @menu
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
370 @end menu
371
372
373 @node Invoking unetcfg, Selecting attachments, Configuring attachments, Configuring attachments
374 @section Invoking @code{unetcfg}
375
376 The @code{unetcfg} program is called as:
377 @example
378 unetcfg [@var{option}@dots{}] @var{command}@dots{}
379 @end example
380
381 The various @var{option}s supported are as follows:
382 @table @samp
383
384 @item -h
385 @itemx --help
386 Displays a helpful and informative summary of @code{unetcfg}'s option
387 syntax.
388
389 @item -V
390 @itemx --version
391 Displays the version number of your copy of @code{unetcfg}.
392
393 @item -v
394 @itemx --verbose
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.
397
398 @end table
399
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.
402
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}).
406
407
408 @node Selecting attachments, Attachment status, Invoking unetcfg, Configuring attachments
409 @section Changing the current attachment
410
411 These commands change the current attachment.  You can use them as often as
412 you like in a single invocation of @code{unetcfg}.
413
414 @deffn Command select @var{filename}
415 Selects @var{filename} as the current attachment.  Further operations will be
416 performed on the named device.
417
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.
420 @end deffn
421
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}.
426
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:
429 @example
430 unetcfg fd stdout show
431 @end example
432 @noindent
433 Don't do this.
434 @end deffn
435
436
437 @node Attachment status, Protocol settings, Selecting attachments, Configuring attachments
438 @section Attachment status
439
440 These commands write useful information about the current attachment to
441 standard output.
442
443 @deffn Command show
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.
447 @end deffn
448
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:
452 @example
453 ifname=`unetcfg fd 3 ifname`
454 ifconfig $ifname localend pointopoint remoteend
455 @end example
456 @end deffn
457
458 @node Protocol settings, Setting debugging options, Attachment status, Configuring attachments
459 @section Protocol settings
460
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.
465
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
470 always IP.
471 @end deffn
472
473
474 @node Setting debugging options,  , Protocol settings, Configuring attachments
475 @section Setting debugging options
476
477
478
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.
482 @end deffn
483
484
485 @c --------------------------------------------------------------------------
486 @node Programming,  , Configuring attachments, Top
487 @chapter Programming Usernet
488
489 This chapter documents Usernet's programming interface.  It's not
490 particularly complicated, you'll be glad to hear.
491
492 @menu
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
496 @end menu
497
498
499 @node Opening and closing, Configuring the interface, Programming, Programming
500 @section Opening and closing
501
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
505 network interface:
506
507 @itemize @bullet
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.
512
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.
516 @end itemize
517
518 Closing a transiently attached device will release and destroy the attached
519 network interface.
520
521
522 @node Configuring the interface, Sending and receiving, Opening and closing, Programming
523 @section Configuring the interface
524
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
528 the distribution.
529
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
532 file descriptor.
533
534 The following @code{ioctl} calls are provided for configuring Usernet
535 attachments.
536
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:
541 @table @code
542
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
546 network interface.
547
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}.
551
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}.
555
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}.
560
561 @item unsigned int uni_flags;
562 An inclusive-OR of the following possible values:
563 @table @code
564 @item UNIF_TRANS
565 Attachment is transient.
566 @item UNIF_OPEN
567 Currently always set.  Ignore this bit.
568 @item UNIF_DEBUG
569 Debugging enabled on this interface.
570 @end table
571
572 @end table
573
574 Example:
575 @example
576 struct unet_info uni;
577 int fd = open("/dev/unet", O_RDWR);
578 if (fd < 0)
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);
583 @end example
584
585 @end deffn
586
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.
592 @end deffn
593
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}.
598 @end deffn
599
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}.
604 @end deffn
605
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.
610 @end deffn
611
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.
615 @end deffn
616
617 @deffn {@code{ioctl} call} UNIOCDUMP
618 Dumps an attachment's information to the kernel log device.
619 @end deffn
620
621 @deffn {@code{ioctl} call} UNIOCGMAXIF
622 Returns the total number of attachments permitted.
623 @end deffn
624
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.
628 @end deffn
629
630
631 @node Sending and receiving,  , Configuring the interface, Programming
632 @section Sending and receiving
633
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
639 stack.
640
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).
646
647 Programs may call @code{select}(2) to wait for packets to arrive from an
648 attached Usernet device.
649
650
651 @c @node Hints,  , Sending and receiving, Programming
652 @c @section Hints
653
654 @c --------------------------------------------------------------------------
655 @contents
656 @bye