Add PCICAP_{ID,NEXTPTR} to avoid using magic number
[dragonfly.git] / usr.sbin / vknetd / vknetd.8
1 .\"
2 .\" Copyright (c) 2008 The DragonFly Project.  All rights reserved.
3 .\" 
4 .\" This code is derived from software contributed to The DragonFly Project
5 .\" by Matthew Dillon <dillon@backplane.com>
6 .\" 
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\" 
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\"    notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\"    notice, this list of conditions and the following disclaimer in
15 .\"    the documentation and/or other materials provided with the
16 .\"    distribution.
17 .\" 3. Neither the name of The DragonFly Project nor the names of its
18 .\"    contributors may be used to endorse or promote products derived
19 .\"    from this software without specific, prior written permission.
20 .\" 
21 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
24 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
25 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
26 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
27 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
28 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
29 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
30 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
31 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" SUCH DAMAGE.
33 .\" 
34 .\" $DragonFly: src/usr.sbin/vknetd/vknetd.8,v 1.3 2008/05/31 12:04:15 swildner Exp $
35 .\"
36 .Dd May 26, 2008
37 .Dt vknetd 8
38 .Os
39 .Sh NAME
40 .Nm vknetd
41 .Nd create a bridged network for (typically user-run) vkernel's
42 .Sh SYNOPSIS
43 .Nm
44 .Op Fl cdU
45 .Op Fl b Ar bridgeN
46 .Op Fl p Ar socket_path
47 .Op Fl t Ar tapN
48 .Op Ar address/cidrbits
49 .Sh DESCRIPTION
50 The
51 .Nm
52 utility creates a virtualized bridged network suitable for vkernel use.
53 The utility was created to simplify vkernel oprations and to allow user-run
54 vkernels to have access to a network.
55 General use is to specify a large 10-dot network which multiple vkernels are
56 then able to connect to, and backfeed the whole mess to a TAP interface.
57 .Pp
58 A vkernel would make use of the virtualized network by specifying
59 .Fl I Ar /dev/vknet
60 instead of a
61 .Xr tap 4
62 interface.
63 Any number of vkernels may connect to the virtual network.
64 .Pp
65 .Nm
66 Implements a simple bridge for all entities connected to it.  A cache
67 of MAC addresses is built up (just like an etherswitch does) and matching
68 packets will be forwarded directly to the proper 'port' (connected clients
69 or TAP interface).  Unknown MACs will be broadcast.
70 .Pp
71 The following options are available:
72 .Bl -tag -width flag
73 .It Fl c
74 Connect into the bridge and monitor activity.  This option currently only
75 monitors broadcast packets.  Packets with cached MACs are not monitored.
76 .It Fl d
77 Debug mode.  Do not go into the background.
78 .It Fl U
79 Unsecure mode.  Act as a pure bridge and do not try to secure the IP
80 space from host visibility.  This is typically used with the
81 .Fl b
82 option to directly bridge
83 .Nm
84 into the host rather then operating it as a separate subnet.
85 .It Fl b Ar bridgeN
86 The
87 .Xr tap 4
88 interface
89 will be bridged into the specified bridge.
90 .It Fl p Ar socket_path
91 Specify where to create the unix domain socket in the filesystem space.
92 By default the socket is called
93 .Pa /dev/vknet .
94 .It Fl t Ar tapN
95 Specify a particular
96 .Xr tap 4
97 interface to use.  If not specified,
98 .Nm
99 will search for an unused tap interface.
100 .It Ar address/cidrbits
101 When operating in secure mode (which is the default), a CIDR block must be
102 specified.  The address is the address you wish to assign to the TAP
103 interface and will sit on both the host and virtual networks if not bridged.
104 The
105 .Ar cidrbits
106 is the number of bits representing the virtual subnet.  For example,
107 10.1.0.1/24 places the tap interface on 10.1.0.1 and gives you an 8 bit
108 subnet capable of handling 254 hosts.
109 .El
110 .Sh EXAMPLES
111 .Li "vknetd 10.1.0.1/16"
112 .Sh REQUIREMENTS
113 .Nm
114 requires that the
115 .Ar if_tap
116 and
117 .Ar if_bridge
118 modules be loaded.
119 In addition, a 'vknet' group must exist in /etc/groups.
120 .Sh FILES
121 .Bl -tag -width /var/log/lastlog -compact
122 .It Pa /dev/tap*
123 TAP interface used to route packets from userland providers back into the
124 real machine.  If not otherwise specified an unused tap interface will be
125 selected.
126 .It Pa /dev/vknet
127 Default socket
128 .Nm
129 sits on waiting for connections.
130 .El
131 .Sh BUGS
132 .Nm
133 defaults to secure mode and will prevent IP spoofing, but the security
134 does not yet handle ARP issues so ARP spoofing can be used to create a
135 denial of service attack on the host network.
136 .Pp
137 .Nm
138 does not currently implement a timeout for its MAC cache.
139 .Sh SEE ALSO
140 .Xr vke 4 ,
141 .Xr vkernel 7 ,
142 .Xr vknet 1
143 .Sh HISTORY
144 The
145 .Nm
146 command was written by Matthew Dillon and first appeared in
147 .Dx 1.13
148 in May 2008.