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