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.Dd June 9, 2026 26.Dt ETHERSWITCHCFG 8 27.Os 28.Sh NAME 29.Nm etherswitchcfg 30.Nd configure a built-in Ethernet switch 31.Sh SYNOPSIS 32.Nm 33.Op Fl "f control file" 34.Cm info 35.Nm 36.Op Fl "f control file" 37.Cm config 38.Ar command parameter 39.Nm 40.Op Fl "f control file" 41.Cm phy 42.Ar phy.register[=value] 43.Nm 44.Op Fl "f control file" 45.Cm port%d 46.Ar [flags] command parameter 47.Nm 48.Op Fl "f control file" 49.Cm reg 50.Ar register[=value] 51.Nm 52.Op Fl "f control file" 53.Cm atu 54.Ar command Op Ar parameter 55.Nm 56.Op Fl "f control file" 57.Cm vlangroup%d 58.Ar command parameter 59.Sh DESCRIPTION 60The 61.Nm 62utility is used to configure an Ethernet switch built into the system. 63.Nm 64accepts a number of options: 65.Pp 66.Bl -tag -width ".Fl f" -compact 67.It Fl "f control file" 68Specifies the 69.Xr etherswitch 4 70control file that represents the switch to be configured. 71It defaults to 72.Pa /dev/etherswitch0 . 73.It Fl m 74When reporting port information, also list available media options for 75that port. 76.It Fl v 77Produce more verbose output. 78Without this flag, lines that represent inactive or empty configuration 79options are omitted. 80.El 81.Ss config 82The config command provides access to global switch configuration 83parameters. 84It support the following commands: 85.Pp 86.Bl -tag -width ".Cm vlan_mode mode" -compact 87.It Cm vlan_mode Ar mode 88Sets the switch VLAN mode (depends on the hardware). 89.El 90.Ss phy 91The phy command provides access to the registers of the PHYs attached 92to or integrated into the switch controller. 93PHY registers are specified as phy.register, 94where 95.Ar phy 96is usually the port number, and 97.Ar register 98is the register number. 99Both can be provided as decimal, octal or hexadecimal numbers in any of the formats 100understood by 101.Xr strtol 3 . 102To set the register value, use the form instance.register=value. 103.Ss port 104The port command selects one of the ports of the switch. 105It supports the following commands: 106.Pp 107.Bl -tag -width ".Ar pvid number" -compact 108.It Cm pvid Ar number 109Sets the default port VID that is used to process incoming frames that are not tagged. 110.It Cm media Ar mediaspec 111Specifies the physical media configuration to be configured for a port. 112.It Cm mediaopt Ar mediaoption 113Specifies a list of media options for a port. 114See 115.Xr ifconfig 8 116for details on 117.Cm media 118and 119.Cm mediaopt . 120.It Cm led Ar number style 121Sets the display style for a given LED. 122Available styles are: 123.Cm default 124(usually flash on activity), 125.Cm on , 126.Cm off , 127and 128.Cm blink . 129Not all switches will support all styles. 130.El 131.Pp 132And the following flags (please note that not all flags 133are supported by all switch drivers): 134.Pp 135.Bl -tag -width ".Fl addtag" -compact 136.It Cm addtag 137Add VLAN tag to each packet sent by the port. 138.It Fl addtag 139Disable the add VLAN tag option. 140.It Cm striptag 141Strip the VLAN tags from the packets sent by the port. 142.It Fl striptag 143Disable the strip VLAN tag option. 144.It Cm striptagingress 145Strip the VLAN tags from the packets received by the port. 146.It Fl striptagingress 147Disable the strip VLAN tag on ingress option. 148.It Cm firstlock 149This options makes the switch port lock on the first MAC address it sees. 150After that, usually you need to reset the switch to learn different 151MAC addresses. 152.It Fl firstlock 153Disable the first lock option. 154Note that sometimes you need to reset the 155switch to really disable this option. 156.It Cm droptagged 157Drop packets with a VLAN tag. 158.It Fl droptagged 159Disable the drop tagged packets option. 160.It Cm dropuntagged 161Drop packets without a VLAN tag. 162.It Fl dropuntagged 163Disable the drop untagged packets option. 164.It Cm doubletag 165Enable QinQ for the port. 166.It Fl doubletag 167Disable QinQ for the port. 168.It Cm ingress 169Enable the ingress filter on the port. 170.It Fl ingress 171Disable the ingress filter. 172.El 173.Ss atu 174The atu command provides access to the Address Translation Unit table 175of the switch, which maps MAC addresses to switch ports. 176It supports the following commands: 177.Pp 178.Bl -tag -width ".Cm flush port number" -compact 179.It Cm dump 180Display the current ATU table entries. 181Each entry shows the MAC address and a bitmask of ports associated with it. 182.It Cm flush all 183Remove all dynamic entries from the ATU table. 184.It Cm flush port Ar number 185Remove all dynamic ATU entries associated with port 186.Ar number . 187.El 188.Ss reg 189The reg command provides access to the registers of the switch controller. 190.Ss vlangroup 191The vlangroup command selects one of the VLAN groups for configuration. 192It supports the following commands: 193.Pp 194.Bl -tag -width ".Cm members" -compact 195.It Cm vlan Ar VID 196Sets the VLAN ID (802.1q VID) for this VLAN group. 197Frames transmitted on tagged member ports of this group will be tagged 198with this VID. 199Incoming frames carrying this tag will be forwarded according to the 200configuration of this VLAN group. 201.It Cm members Ar port,... 202Configures which ports are to be a member of this VLAN group. 203The port numbers are given as a comma-separated list. 204Each port can optionally be followed by 205.Dq t 206to indicate that frames on this port are tagged. 207.El 208.Sh FILES 209.Bl -tag -width /dev/etherswitch? -compact 210.It Pa /dev/etherswitch? 211Control file for the Ethernet switch driver. 212.El 213.Sh EXAMPLES 214Configure VLAN group 1 with a VID of 2 and make ports 0 and 5 its members 215while excluding all other ports. 216Port 5 will send and receive tagged frames while port 0 will be untagged. 217Incoming untagged frames on port 0 are assigned to vlangroup1. 218.Pp 219.Dl # etherswitchcfg vlangroup1 vlan 2 members 0,5t port0 pvid 2 220.Sh SEE ALSO 221.Xr etherswitch 4 222.Sh HISTORY 223.Nm 224first appeared in 225.Fx 10.0 . 226.Sh AUTHORS 227.An Stefan Bethke 228