Sort sections in various manual pages.
[dragonfly.git] / usr.sbin / vknetd / vknetd.8
CommitLineData
dbfd168b
MD
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.\"
3fc0dfa2 34.\" $DragonFly: src/usr.sbin/vknetd/vknetd.8,v 1.3 2008/05/31 12:04:15 swildner Exp $
dbfd168b 35.\"
26c2ab48 36.Dd May 21, 2009
cf4f0088 37.Dt vknetd 8
dbfd168b
MD
38.Os
39.Sh NAME
cf4f0088 40.Nm vknetd
12b657fc 41.Nd create a bridged network for (typically user-run) vkernels
dbfd168b
MD
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
50The
51.Nm
52utility creates a virtualized bridged network suitable for vkernel use.
53The utility was created to simplify vkernel oprations and to allow user-run
54vkernels to have access to a network.
55General use is to specify a large 10-dot network which multiple vkernels are
56then able to connect to, and backfeed the whole mess to a TAP interface.
57.Pp
58A vkernel would make use of the virtualized network by specifying
1ecab6b9 59.Fl I Ar /var/run/vknet
dbfd168b
MD
60instead of a
61.Xr tap 4
62interface.
63Any number of vkernels may connect to the virtual network.
64.Pp
65.Nm
e96ee093
SW
66Implements a simple bridge for all entities connected to it.
67A cache
dbfd168b
MD
68of MAC addresses is built up (just like an etherswitch does) and matching
69packets will be forwarded directly to the proper 'port' (connected clients
e96ee093
SW
70or TAP interface).
71Unknown MACs will be broadcast.
dbfd168b
MD
72.Pp
73The following options are available:
74.Bl -tag -width flag
75.It Fl c
e96ee093
SW
76Connect into the bridge and monitor activity.
77This option currently only monitors broadcast packets.
78Packets with cached MACs are not monitored.
dbfd168b 79.It Fl d
e96ee093
SW
80Debug mode.
81Do not go into the background.
dbfd168b 82.It Fl U
e96ee093
SW
83Unsecure mode.
84Act as a pure bridge and do not try to secure the IP
85space from host visibility.
86This is typically used with the
dbfd168b
MD
87.Fl b
88option to directly bridge
89.Nm
90into the host rather then operating it as a separate subnet.
91.It Fl b Ar bridgeN
92The
93.Xr tap 4
94interface
95will be bridged into the specified bridge.
96.It Fl p Ar socket_path
97Specify where to create the unix domain socket in the filesystem space.
98By default the socket is called
1ecab6b9 99.Pa /var/run/vknet .
dbfd168b
MD
100.It Fl t Ar tapN
101Specify a particular
102.Xr tap 4
e96ee093
SW
103interface to use.
104If not specified,
dbfd168b
MD
105.Nm
106will search for an unused tap interface.
107.It Ar address/cidrbits
108When operating in secure mode (which is the default), a CIDR block must be
e96ee093 109specified.
26c2ab48 110It is optional in unsecure mode.
e96ee093 111The address is the address you wish to assign to the TAP
dbfd168b
MD
112interface and will sit on both the host and virtual networks if not bridged.
113The
114.Ar cidrbits
e96ee093
SW
115is the number of bits representing the virtual subnet.
116For example,
dbfd168b
MD
11710.1.0.1/24 places the tap interface on 10.1.0.1 and gives you an 8 bit
118subnet capable of handling 254 hosts.
26c2ab48
SW
119An address of 0.0.0.0 is allowed as a special case in secure mode so that
120bootp
121.Xr ( dhclient 8 )
122can get through.
dbfd168b 123.El
dbfd168b
MD
124.Sh FILES
125.Bl -tag -width /var/log/lastlog -compact
126.It Pa /dev/tap*
127TAP interface used to route packets from userland providers back into the
e96ee093
SW
128real machine.
129If not otherwise specified an unused tap interface will be selected.
1ecab6b9 130.It Pa /var/run/vknet
dbfd168b
MD
131Default socket
132.Nm
133sits on waiting for connections.
134.El
a68e0df0
SW
135.Sh EXAMPLES
136.Li "vknetd 10.1.0.1/16"
137.Sh REQUIREMENTS
dbfd168b 138.Nm
a68e0df0
SW
139requires that the
140.Ar if_tap
141and
142.Ar if_bridge
143modules be loaded.
144In addition, a 'vknet' group must exist in /etc/groups.
dbfd168b 145.Sh SEE ALSO
666855ca 146.Xr vknet 1 ,
3fc0dfa2 147.Xr vke 4 ,
666855ca 148.Xr vkernel 7
dbfd168b
MD
149.Sh HISTORY
150The
151.Nm
152command was written by Matthew Dillon and first appeared in
153.Dx 1.13
154in May 2008.
a68e0df0
SW
155.Sh BUGS
156.Nm
157defaults to secure mode and will prevent IP spoofing, but the security
158does not yet handle ARP issues so ARP spoofing can be used to create a
159denial of service attack on the host network.
160.Pp
161.Nm
162does not currently implement a timeout for its MAC cache.