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