[dragonfly.git] / usr.bin / vknet / vknet.1

.\"
.\" Copyright (c) 2008 The DragonFly Project.  All rights reserved.
.\" 
.\" This code is derived from software contributed to The DragonFly Project
.\" by Matthew Dillon <dillon@backplane.com>
.\" 
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\" 3. Neither the name of The DragonFly Project nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific, prior written permission.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\" 
.\" $DragonFly: src/usr.bin/vknet/vknet.1,v 1.4 2008/07/21 23:42:23 swildner Exp $
.\"
.Dd May 27, 2008
.Dt vknet 1
.Os
.Sh NAME
.Nm vknet
.Nd create a bridged network between two hosts over
.Xr ssh 1
.Sh SYNOPSIS
.Nm
.Op Fl C
.Op Fl b Ar local-bridge
.Op Fl B Ar remote-bridge
.Op Fl r Ar delay[:retries]
.Ar local-spec
.Ar [user@]host[:remote-spec]
.Nm
.Op Fl S
.Op Fl b Ar local-bridge
.Ar local
.Sh DESCRIPTION
The
.Nm
utility connects the local machine's network to the remote machine's
network over a SSH connection.
.Pp
The local and remote specification
typically supplies a path to a vknetd socket such as
.Pa /dev/vknet ,
but may also specify a
.Xr tap 4
interface or the
.Ar auto
keyword to automatically allocate a
.Xr tap 4
interface.
.Pp
If a TAP interface is used on any given side it can be bridged on that
side.
.Pp
If a unix domain socket path is specified
.Nm
connects to use via the SOCK_SEQPACKET socket type.
.Xr vknetd 8
sockets cannot be bridged (but you don't want to anyway because vknetd
is already typically connected to a potentially bridged TAP interface).
.Pp
The following options are available:
.Bl -tag -width flag
.It Fl C
Request that
.Xr ssh 1
compress the connection.
.It Fl b Ar local-bridge
Specify that the local specification, which must be a TAP interface or
.Ar auto ,
be bridged to the specified bridge.
.It Fl B Ar remote-bridge
Specify that the remote specification, which must be a TAP interface or
.Ar auto ,
be bridged to the specified bridge on the remote side.
.It Fl r Ar delay[:retries]
If the link cannot be established or is lost, delay the specified number
of seconds and retry.  If no retry limit is specified an infinite number
of retries will be made.
.It Fl S
This option is used by the
.Nm
run on the remote side of the
.Xr ssh 1
link to use stdin and stdout as its
remote specification.  This option is typically not specified manually.
.El
.Sh REQUIREMENTS
You may have to load the
.Ar if_tap
and/or
.Ar if_bridge
modules, or run
.Xr vknetd 8
to provide an interconnect to the local and remote machine's nework.
.Sh FILES
.Bl -tag -width /var/log/lastlog -compact
.It Pa /dev/tap*
TAP interface used to route packets from userland providers back into the
real machine.  If not otherwise specified an unused TAP interface will be
selected.
.Pp
.It Pa /dev/vknet
Socket
.Nm
typically connects to, established by
.Xr vknetd 8 .
.El
.Sh EXAMPLES
.Li "vknet -r 5 /dev/vknet myhomesystem:/dev/vknet"
.Pp
.Li "vknet -r 5 -b bridge0 -B bridge0 auto myhomesystem:auto"
.Sh SEE ALSO
.Xr vke 4 ,
.Xr vkernel 7 ,
.Xr vknetd 8
.Sh HISTORY
The
.Nm
command was written by Matthew Dillon and first appeared in
.Dx 1.13
in May 2008.
.Sh BUGS
There are currently no known bugs.
Commit	Line	Data
cf4f0088 MD	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	.\"
e34536f9	34	.\" $DragonFly: src/usr.bin/vknet/vknet.1,v 1.4 2008/07/21 23:42:23 swildner Exp $
cf4f0088 MD	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
083f1589	42	.Xr ssh 1
cf4f0088 MD	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
083f1589	72	If a TAP interface is used on any given side it can be bridged on that
cf4f0088 MD	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
083f1589	103	run on the remote side of the
e34536f9	104	.Xr ssh 1
083f1589	105	link to use stdin and stdout as its
cf4f0088 MD	106	remote specification. This option is typically not specified manually.
cf4f0088 MD	107	.El
cf4f0088 MD	108	.Sh REQUIREMENTS
	109	You may have to load the
	110	.Ar if_tap
	111	and/or
	112	.Ar if_bridge
	113	modules, or run
	114	.Xr vknetd 8
	115	to provide an interconnect to the local and remote machine's nework.
	116	.Sh FILES
	117	.Bl -tag -width /var/log/lastlog -compact
	118	.It Pa /dev/tap*
	119	TAP interface used to route packets from userland providers back into the
083f1589	120	real machine. If not otherwise specified an unused TAP interface will be
cf4f0088 MD	121	selected.
	122	.Pp
	123	.It Pa /dev/vknet
	124	Socket
	125	.Nm
	126	typically connects to, established by
	127	.Xr vknetd 8 .
	128	.El
a68e0df0 SW	129	.Sh EXAMPLES
	130	.Li "vknet -r 5 /dev/vknet myhomesystem:/dev/vknet"
	131	.Pp
	132	.Li "vknet -r 5 -b bridge0 -B bridge0 auto myhomesystem:auto"
cf4f0088	133	.Sh SEE ALSO
3fc0dfa2	134	.Xr vke 4 ,
cf4f0088	135	.Xr vkernel 7 ,
cf4f0088 MD	136	.Xr vknetd 8
	137	.Sh HISTORY
	138	The
	139	.Nm
	140	command was written by Matthew Dillon and first appeared in
	141	.Dx 1.13
	142	in May 2008.
a68e0df0 SW	143	.Sh BUGS
a68e0df0 SW	144	There are currently no known bugs.