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