xref: /freebsd/sbin/etherswitchcfg/etherswitchcfg.8 (revision c7d813a93eeb447470734c9bc0c140d90a54c271)
1.\" Copyright (c) 2011-2012 Stefan Bethke.
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD$
26.\"
27.Dd October 2, 2016
28.Dt ETHERSWITCHCFG 8
29.Os
30.Sh NAME
31.Nm etherswitchcfg
32.Nd configure a built-in Ethernet switch
33.Sh SYNOPSIS
34.Nm
35.Op Fl "f control file"
36.Cm info
37.Nm
38.Op Fl "f control file"
39.Cm config
40.Ar command parameter
41.Nm
42.Op Fl "f control file"
43.Cm phy
44.Ar phy.register[=value]
45.Nm
46.Op Fl "f control file"
47.Cm port%d
48.Ar [flags] command parameter
49.Nm
50.Op Fl "f control file"
51.Cm reg
52.Ar register[=value]
53.Nm
54.Op Fl "f control file"
55.Cm vlangroup%d
56.Ar command parameter
57.Sh DESCRIPTION
58The
59.Nm
60utility is used to configure an Ethernet switch built into the system.
61.Nm
62accepts a number of options:
63.Pp
64.Bl -tag -width ".Fl f" -compact
65.It Fl "f control file"
66Specifies the
67.Xr etherswitch 4
68control file that represents the switch to be configured.
69It defaults to
70.Pa /dev/etherswitch0 .
71.It Fl m
72When reporting port information, also list available media options for
73that port.
74.It Fl v
75Produce more verbose output.
76Without this flag, lines that represent inactive or empty configuration
77options are omitted.
78.El
79.Ss config
80The config command provides access to global switch configuration
81parameters.
82It support the following commands:
83.Pp
84.Bl -tag -width ".Cm vlan_mode mode" -compact
85.It Cm vlan_mode Ar mode
86Sets the switch VLAN mode (depends on the hardware).
87.El
88.Ss phy
89The phy command provides access to the registers of the PHYs attached
90to or integrated into the switch controller.
91PHY registers are specified as phy.register,
92where
93.Ar phy
94is usually the port number, and
95.Ar register
96is the register number.
97Both can be provided as decimal, octal or hexadecimal numbers in any of the formats
98understood by
99.Xr strtol 3 .
100To set the register value, use the form instance.register=value.
101.Ss port
102The port command selects one of the ports of the switch.
103It supports the following commands:
104.Pp
105.Bl -tag -width ".Ar pvid number" -compact
106.It Cm pvid Ar number
107Sets the default port VID that is used to process incoming frames that are not tagged.
108.It Cm media Ar mediaspec
109Specifies the physical media configuration to be configured for a port.
110.It Cm mediaopt Ar mediaoption
111Specifies a list of media options for a port.
112See
113.Xr ifconfig 8
114for details on
115.Cm media
116and
117.Cm mediaopt .
118.It Cm led Ar number style
119Sets the display style for a given LED.
120Available styles are:
121.Cm default
122(usually flash on activity),
123.Cm on ,
124.Cm off ,
125and
126.Cm blink .
127Not all switches will support all styles.
128.El
129.Pp
130And the following flags (please note that not all flags
131are supported by all switch drivers):
132.Pp
133.Bl -tag -width ".Fl addtag" -compact
134.It Cm addtag
135Add VLAN tag to each packet sent by the port.
136.It Fl addtag
137Disable the add VLAN tag option.
138.It Cm striptag
139Strip the VLAN tags from the packets sent by the port.
140.It Fl striptag
141Disable the strip VLAN tag option.
142.It Cm firstlock
143This options makes the switch port lock on the first MAC address it sees.
144After that, usually you need to reset the switch to learn different
145MAC addresses.
146.It Fl firstlock
147Disable the first lock option.
148Note that sometimes you need to reset the
149switch to really disable this option.
150.It Cm dropuntagged
151Drop packets without a VLAN tag.
152.It Fl dropuntagged
153Disable the drop untagged packets option.
154.It Cm doubletag
155Enable QinQ for the port.
156.It Fl doubletag
157Disable QinQ for the port.
158.It Cm ingress
159Enable the ingress filter on the port.
160.It Fl ingress
161Disable the ingress filter.
162.El
163.Ss reg
164The reg command provides access to the registers of the switch controller.
165.Ss vlangroup
166The vlangroup command selects one of the VLAN groups for configuration.
167It supports the following commands:
168.Pp
169.Bl -tag -width ".Cm members" -compact
170.It Cm vlan Ar VID
171Sets the VLAN ID (802.1q VID) for this VLAN group.
172Frames transmitted on tagged member ports of this group will be tagged
173with this VID.
174Incoming frames carrying this tag will be forwarded according to the
175configuration of this VLAN group.
176.It Cm members Ar port,...
177Configures which ports are to be a member of this VLAN group.
178The port numbers are given as a comma-separated list.
179Each port can optionally be followed by
180.Dq t
181to indicate that frames on this port are tagged.
182.El
183.Sh FILES
184.Bl -tag -width /dev/etherswitch? -compact
185.It Pa /dev/etherswitch?
186Control file for the Ethernet switch driver.
187.El
188.Sh EXAMPLES
189Configure VLAN group 1 with a VID of 2 and make ports 0 and 5 its members
190while excluding all other ports.
191Port 5 will send and receive tagged frames while port 0 will be untagged.
192Incoming untagged frames on port 0 are assigned to vlangroup1.
193.Pp
194.Dl # etherswitchcfg vlangroup1 vlan 2 members 0,5t port0 pvid 2
195.Sh SEE ALSO
196.Xr etherswitch 4
197.Sh HISTORY
198.Nm
199first appeared in
200.Fx 10.0 .
201.Sh AUTHORS
202.An Stefan Bethke
203