sbin/etherswitchcfg/etherswitchcfg.8

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