usr.bin/vknet/vknet.1

   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.bin/vknet/vknet.1,v 1.4 2008/07/21 23:42:23 swildner Exp $
  35 .\"
  36 .Dd May 27, 2008
  37 .Dt vknet 1
  38 .Os
  39 .Sh NAME
  40 .Nm vknet
  41 .Nd create a bridged network between two hosts over
  42 .Xr ssh 1
  43 .Sh SYNOPSIS
  44 .Nm
  45 .Op Fl C
  46 .Op Fl b Ar local-bridge
  47 .Op Fl B Ar remote-bridge
  48 .Op Fl r Ar delay[:retries]
  49 .Ar local-spec
  50 .Ar [user@]host[:remote-spec]
  51 .Nm
  52 .Op Fl S
  53 .Op Fl b Ar local-bridge
  54 .Ar local
  55 .Sh DESCRIPTION
  56 The
  57 .Nm
  58 utility connects the local machine's network to the remote machine's
  59 network over a SSH connection.
  60 .Pp
  61 The local and remote specification
  62 typically supplies a path to a vknetd socket such as
  63 .Pa /dev/vknet ,
  64 but may also specify a
  65 .Xr tap 4
  66 interface or the
  67 .Ar auto
  68 keyword to automatically allocate a
  69 .Xr tap 4
  70 interface.
  71 .Pp
  72 If a TAP interface is used on any given side it can be bridged on that
  73 side.
  74 .Pp
  75 If a unix domain socket path is specified
  76 .Nm
  77 connects to use via the SOCK_SEQPACKET socket type.
  78 .Xr vknetd 8
  79 sockets cannot be bridged (but you don't want to anyway because vknetd
  80 is already typically connected to a potentially bridged TAP interface).
  81 .Pp
  82 The following options are available:
  83 .Bl -tag -width flag
  84 .It Fl C
  85 Request that
  86 .Xr ssh 1
  87 compress the connection.
  88 .It Fl b Ar local-bridge
  89 Specify that the local specification, which must be a TAP interface or
  90 .Ar auto ,
  91 be bridged to the specified bridge.
  92 .It Fl B Ar remote-bridge
  93 Specify that the remote specification, which must be a TAP interface or
  94 .Ar auto ,
  95 be bridged to the specified bridge on the remote side.
  96 .It Fl r Ar delay[:retries]
  97 If the link cannot be established or is lost, delay the specified number
  98 of seconds and retry.  If no retry limit is specified an infinite number
  99 of retries will be made.
 100 .It Fl S
 101 This option is used by the
 102 .Nm
 103 run on the remote side of the
 104 .Xr ssh 1
 105 link to use stdin and stdout as its
 106 remote specification.  This option is typically not specified manually.
 107 .El
 108 .Sh EXAMPLES
 109 .Li "vknet -r 5 /dev/vknet myhomesystem:/dev/vknet"
 110 .Pp
 111 .Li "vknet -r 5 -b bridge0 -B bridge0 auto myhomesystem:auto"
 112 .Sh REQUIREMENTS
 113 You may have to load the
 114 .Ar if_tap
 115 and/or
 116 .Ar if_bridge
 117 modules, or run
 118 .Xr vknetd 8
 119 to provide an interconnect to the local and remote machine's nework.
 120 .Sh FILES
 121 .Bl -tag -width /var/log/lastlog -compact
 122 .It Pa /dev/tap*
 123 TAP interface used to route packets from userland providers back into the
 124 real machine.  If not otherwise specified an unused TAP interface will be
 125 selected.
 126 .Pp
 127 .It Pa /dev/vknet
 128 Socket
 129 .Nm
 130 typically connects to, established by
 131 .Xr vknetd 8 .
 132 .El
 133 .Sh BUGS
 134 There are currently no known bugs.
 135 .Sh SEE ALSO
 136 .Xr vke 4 ,
 137 .Xr vkernel 7 ,
 138 .Xr vknetd 8
 139 .Sh HISTORY
 140 The
 141 .Nm
 142 command was written by Matthew Dillon and first appeared in
 143 .Dx 1.13
 144 in May 2008.