24cb6de8db839efcc435d0f343425a8b7b4a9640
[dragonfly.git] / 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.