Create a new daemon called vknetd. This daemon uses the new SOCK_SEQPACKET
[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.\"
34.\" $DragonFly: src/usr.sbin/vknetd/vknetd.8,v 1.1 2008/05/27 01:58:01 dillon Exp $
35.\"
36.Dd May 26, 2008
37.Dt vknet 8
38.Os
39.Sh NAME
40.Nm vknet
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
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
59.Fl I Ar /dev/vknet
60instead of a
61.Xr tap 4
62interface.
63Any number of vkernels may connect to the virtual network.
64.Pp
65.Nm
66Implements a simple bridge for all entities connected to it. A cache
67of MAC addresses is built up (just like an etherswitch does) and matching
68packets will be forwarded directly to the proper 'port' (connected clients
69or TAP interface). Unknown MACs will be broadcast.
70.Pp
71The following options are available:
72.Bl -tag -width flag
73.It Fl c
74Connect into the bridge and monitor activity. This option currently only
75monitors broadcast packets. Packets with cached MACs are not monitored.
76.It Fl d
77Debug mode. Do not go into the background.
78.It Fl U
79Unsecure mode. Act as a pure bridge and do not try to secure the IP
80space from host visibility. This is typically used with the
81.Fl b
82option to directly bridge
83.Nm
84into the host rather then operating it as a separate subnet.
85.It Fl b Ar bridgeN
86The
87.Xr tap 4
88interface
89will be bridged into the specified bridge.
90.It Fl p Ar socket_path
91Specify where to create the unix domain socket in the filesystem space.
92By default the socket is called
93.Pa /dev/vknet .
94.It Fl t Ar tapN
95Specify a particular
96.Xr tap 4
97interface to use. If not specified,
98.Nm
99will search for an unused tap interface.
100.It Ar address/cidrbits
101When operating in secure mode (which is the default), a CIDR block must be
102specified. The address is the address you wish to assign to the TAP
103interface and will sit on both the host and virtual networks if not bridged.
104The
105.Ar cidrbits
106is the number of bits representing the virtual subnet. For example,
10710.1.0.1/24 places the tap interface on 10.1.0.1 and gives you an 8 bit
108subnet capable of handling 254 hosts.
109.El
110.Sh EXAMPLES
111.Li "vknetd 10.1.0.1/16"
112.Pp
113.Sh REQUIREMENTS
114.Nm
115requires that the
116.Ar if_tap
117and
118.Ar if_bridge
119modules be loaded.
120In addition, a 'vknet' group must exist in /etc/groups.
121.Sh FILES
122.Bl -tag -width /var/log/lastlog -compact
123.It Pa /dev/tap*
124TAP interface used to route packets from userland providers back into the
125real machine. If not otherwise specified an unused tap interface will be
126selected.
127.It Pa /dev/vknet
128Default socket
129.Nm
130sits on waiting for connections.
131.El
132.Sh BUGS
133.Nm
134defaults to secure mode and will prevent IP spoofing, but the security
135does not yet handle ARP issues so ARP spoofing can be used to create a
136denial of service attack on the host network.
137.Pp
138.Nm
139does not currently implement a timeout for its MAC cache.
140.Sh SEE ALSO
141.Xr vkernel 7 ,
142.Xr vke 7
143.Sh HISTORY
144The
145.Nm
146command was written by Matthew Dillon and first appeared in
147.Dx 1.13
148in May 2008.