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.Dd December 5, 2011 35.Dt VKNETD 8 36.Os 37.Sh NAME 38.Nm vknetd 39.Nd create a bridged network for (typically user-run) vkernels 40.Sh SYNOPSIS 41.Nm 42.Op Fl cdU 43.Op Fl b Ar bridgeN 44.Op Fl p Ar socket_path 45.Op Fl i Ar pidfile 46.Op Fl t Ar tapN 47.Op Ar address Ns / Ns Ar cidrbits 48.Sh DESCRIPTION 49The 50.Nm 51utility creates a virtualized bridged network suitable for vkernel use. 52The utility was created to simplify 53.Nm vkernel 54operations and to allow user-run 55vkernels to have access to a network. 56General use is to specify a large 10-dot network which multiple vkernels are 57then able to connect to, and backfeed the whole mess to a TAP interface. 58.Pp 59A 60.Nm vkernel 61would make use of the virtualized network by specifying 62.Fl I Ar /var/run/vknet 63instead of a 64.Xr tap 4 65interface. 66Any number of vkernels may connect to the virtual network. 67.Pp 68.Nm 69Implements a simple bridge for all entities connected to it. 70A cache 71of MAC addresses is built up (just like an ethernet switch does) and matching 72packets will be forwarded directly to the proper 73.Sq port 74(connected clients or TAP interface). 75Unknown MACs will be broadcast. 76.Pp 77The following options are available: 78.Bl -tag -width flag 79.It Fl c 80Connect into the bridge and monitor activity. 81This option currently only monitors broadcast packets. 82Packets with cached MACs are not monitored. 83.It Fl d 84Debug mode. 85Do not go into the background. 86.It Fl U 87Unsecure mode. 88Act as a pure bridge and do not try to secure the IP 89space from host visibility. 90This is typically used with the 91.Fl b 92option to directly bridge 93.Nm 94into the host rather than operating it as a separate subnet. 95All IP protocols will be allowed through and no address checking 96will be done. 97.Pp 98When this option is not specified 99.Nm 100runs in secure mode and only allowed through ICMP, UDP, and TCP, 101and only IP addresses within the space defined on the command line. 102.Nm 103was started. 104.It Fl b Ar bridgeN 105The 106.Xr tap 4 107interface 108will be bridged into the specified bridge. 109.It Fl p Ar socket_path 110Specify where to create the unix domain socket in the filesystem space. 111By default the socket is called 112.Pa /var/run/vknet . 113.It Fl i Ar pidfile 114When specified, write process id to 115.Ar pidfile 116instead of the default 117.Pa /var/run/vknetd.pid . 118.It Fl t Ar tapN 119Specify a particular 120.Xr tap 4 121interface to use. 122If not specified, 123.Nm 124will search for an unused TAP interface. 125.It Ar address Ns / Ns Ar cidrbits 126When operating in secure mode (which is the default), a CIDR block must be 127specified. 128It is optional in unsecure mode. 129The 130.Ar address 131is the address you wish to assign to the TAP 132interface and will sit on both the host and virtual networks if not bridged. 133The 134.Ar cidrbits 135is the number of bits representing the virtual subnet. 136For example, 13710.1.0.1/24 places the TAP interface on 10.1.0.1 and gives you an 8 bit 138subnet capable of handling 254 hosts. 139An address of 0.0.0.0 is allowed as a special case in secure mode so that 140bootp ( 141.Xr dhclient 8 ) 142can get through. 143.El 144.Sh FILES 145.Bl -tag -width ".Pa /var/run/vknet" -compact 146.It Pa /dev/tap* 147TAP interface used to route packets from userland providers back into the 148real machine. 149If not otherwise specified an unused TAP interface will be selected. 150.It Pa /var/run/vknet 151Default socket 152.Nm 153sits on waiting for connections. 154.El 155.Sh EXAMPLES 156.Dl "vknetd 10.1.0.1/16" 157.Sh REQUIREMENTS 158.Nm 159requires that the 160.Nm if_tap 161and 162.Nm if_bridge 163modules be loaded. 164In addition, a 165.Dq vknet 166group must exist in 167.Pa /etc/groups . 168.Sh SEE ALSO 169.Xr vknet 1 , 170.Xr bridge 4 , 171.Xr tap 4 , 172.Xr vke 4 , 173.Xr vkernel 7 , 174.Xr dhclient 8 175.Sh HISTORY 176The 177.Nm 178command was written by Matthew Dillon and first appeared in 179.Dx 1.13 180in May 2008. 181.Sh BUGS 182.Nm 183defaults to secure mode and will prevent IP spoofing, but the security 184does not yet handle ARP issues so ARP spoofing can be used to create a 185denial of service attack on the host network. 186.Pp 187.Nm 188does not currently implement a timeout for its MAC cache. 189