plan9fox/sys/man/3/bridge

.TH BRIDGE 3
.SH NAME
bridge \- IP Ethernet bridge
.SH SYNOPSIS
.nf
.B bind -a #B\fIb\fP /net

.B /net/bridge\fIb\fP/ctl
.B /net/bridge\fIb\fP/cache
.B /net/bridge\fIb\fP/log
.B /net/bridge\fIb\fP/stats
.BI /net/bridge\fIb\fP/ n
.BI /net/bridge\fIb\fP/ n /ctl
.BI /net/bridge\fIb\fP/ n /local
.BI /net/bridge\fIb\fP/ n /status
.fi
.SH DESCRIPTION
The
.I bridge
device bridges packets amongst Ethernet interfaces.
The number
.I b
in the bind is optional and selects a particular bridge
(default 0).
.PP
The
.B /net/bridge0
directory contains
.BR ctl ,
.BR cache ,
.BR log ,
and
.B stats
files, and numbered subdirectories for each physical interface.
.PP
Opening the
.B ctl
file reserves an interface.
The file descriptor returned from the
.IR open (2)
will point to the control file,
.BR ctl ,
of the newly allocated interface.
Reading
.B ctl
returns a text string representing the number of the interface.
Writing
.B ctl
alters aspects of the interface.
The possible
.I ctl
messages are:
.TP
.BI "bind ether " "name ownhash path [pvid[#prio][,vlans...]]"
Treat the device mounted at
.I path
(e.g.,
.LR /net/ether0 )
as an Ethernet medium
and associate it with this bridge (forward its packets to the
other interfaces associated with this bridge).
.I Ownhash
is an `owner hash'.
The optional
.I [pvid[#prio][,vlans...]]
argument is explained in
.B vlan
command below.
.TP
.BI "bind tunnel " "name ownhash path path2 [pvid[#prio][,vlans...]]"
Treat the device mounted at
.I path
as a network tunnel carrying Ethernet packets,
the device mounted at
.I path2
as an Ethernet
and associate them with this bridge
(forward its packets to the
other interfaces associated with this bridge).
Read packets from the
.I path
interface and write them to the
.I path2
interface.
Such tunnels have an MTU of 1400 bytes.
.TP
.BI "vlan " "pvid[#prio][,vlans...] type name [ownhash]"
Change the 802.1Q VLAN configuration of a port identified by
.IR type ,
.I name
and
.I ownhash.
The
.I pvid
is the "Native" VLAN id associated with untagged packets
on a port.
Packets with a VLAN id of
.I pvid
will be send out untagged on the port.
Untagged packets received on the port will be tagged with the
.IR pvid .
When
.I pvid
was not specified in a
.B bind
command above,
ports default to a
.I pvid
of
.BR "1" .
The
.I pvid
can be specified as 0 when untagged packets should
be ignored on a port.
The optional
.I prio
argument specifies the default priority to assign to a
incoming untagged packet on the port between 0 (lowest,
default) and 7 (highest).
The
.I vlans...
argument specifies comma separated ranges of other
VLAN id's that the port is a member of (for trunk ports).
Membership means the port is accepting
tagged packets with VLAN id's listed here and
ignores VLAN id's not listed here. Once accepted,
packets are forwarded only to other ports that are
members of the same (accepted) VLAN id.
Unless
.I pvid
is
.BR "0" ,
a port is always a member of its own
.I pvid
VLAN id,
so it does not need to be listed twice.
.TP
.BI "unbind " "type name [ownhash]"
Disassociate the interface associated with
.I name
from this bridge.
.I Type
must be
.L ether
or
.LR tunnel .
.TP
.B cacheflush
Clear the cache of (destination MAC address, VLAN id, port) tuples.
.TP
.BI "delay " "delay0 delayn"
Set the
.I delay0
and
.I delayn
parameters.
.I delay0
is the constant microsecond delay per packet
and
.I delayn
is the microsecond delay per byte.
.TP
.BI "set " option
Set bridge
.IR option .
The only known option is
.LR tcpmss ,
which limits the TCP Maximum Segment Size of
TCP packets passing through to 1300 bytes.
.TP
.BI "clear " option
Clear bridge
.IR option .
.PP
Reading
.I stats
returns statistics about the bridge.
.PP
Reading the
.I log
file returns data from the bridge's log
and will block at end of file awaiting new data.
.PP
Reading the
.B cache
file prints the cache of (destination MAC address, VLAN id, port) tuples,
one entry per line.
The format is:
the destination MAC (e.g., Ethernet) address in hex,
VLAN id,
port number,
count of packets from this address,
count of packets to this address,
expiry time in seconds since the epoch,
and
.L e
for expired entries or
.L v
for valid entries.
.PP
In a connection subdirectory,
.B ctl
and
.B local
don't do anything,
but
.B status
returns a one-line status summary.
.SH EXAMPLES
Set up a network bridge between two Ethernets
.RL ( #l0
and
.LR #l1 ).
.IP
.EX
bind -a '#B' /net
bind -a '#l1' /net
echo 'bind ether outer 0 /net/ether0' >/net/bridge0/ctl
echo 'bind ether inner 0 /net/ether1' >/net/bridge0/ctl
.EE
.PP
Set up bridge1 with 3 access ports and a trunk port.
.IP
.EX
# create bridge1
bind -a '#B1' /net

# nic for trunk carrying only tagged vlans 10,20 and 30
bind -a '#l0' /net
echo 'bind ether trunk 0 /net/ether0 0,10,20,30' >/net/bridge1/ctl

# create virtual nics for access ports
bind -a '#l1:sink ea=001122334401' /net
bind -a '#l2:sink ea=001122334402' /net
bind -a '#l3:sink ea=001122334403' /net
echo 'bind ether port1 0 /net/ether1 10' >/net/bridge1/ctl
echo 'bind ether port2 0 /net/ether2 20' >/net/bridge1/ctl
echo 'bind ether port3 0 /net/ether3 30' >/net/bridge1/ctl
.EE
.SH "SEE ALSO"
.IR ip (3),
.IR ether (3)
.SH SOURCE
.B /sys/src/9/port/devbridge.c