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