Newer
Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
\input texinfo @c -*-texinfo-*-
%
% wrs-user-manual.in - main file for the documentation
%
%%%%
%------------------------------------------------------------------------------
%
% NOTE FOR THE UNAWARE USER
% =========================
%
% This file is a texinfo source. It isn't the binary file of some strange
% editor of mine. If you want ASCII, you should "make wrs-user-manual.txt".
%
%------------------------------------------------------------------------------
%
% This is not a conventional info file...
% I use three extra features:
% - The '%' as a comment marker, if at beginning of line ("\%" -> "%")
% - leading blanks are allowed (this is something I cannot live without)
% - braces are automatically escaped when they appear in example blocks
%
@comment %**start of header
@documentlanguage en
@documentencoding ISO-8859-1
@setfilename wrs-user-manual.info
@settitle wrs-user-manual
@iftex
@afourpaper
@end iftex
@paragraphindent none
@comment %**end of header
@setchapternewpage off
@set update-month December 2016
@c the release name below is substituted at build time
@set release __RELEASE_GIT_ID__
@finalout
@titlepage
@title White Rabbit Switch: User's Manual
@subtitle Information about configuring the White Rabbit switch, for final users
@subtitle @value{update-month} (@value{release})
@author Alessandro Rubini, Adam Wujek, Benoit Rat, Federico Vaga, ...
@end titlepage
@headings single
@c ##########################################################################
@iftex
@contents
@end iftex
@c ##########################################################################
@c in texinfo we are mandated to have a Top node
@node Top
@top Introduction
The White Rabbit switch (or @sc{wrs}) is a major component of the
White Rabbit (@sc{wr}) network. Like any modern managed switch, the
@sc{wrs} includes a CPU with its own operating system.
This manual is for people installing @sc{wrs} devices, who need to
configure them in their network.
@c ##########################################################################
@node WRS Documentation
@chapter WRS Documentation
Up to and including release v4.0 of @sc{wrs} software this manual
didn't exist, and the ``WRS Build Manual'' included some information
about configuration.
@c ==========================================================================
@node The Official Manuals
@section The Official Manuals
This is the current set of manuals that accompany the @sc{wrs}:
@itemize @bullet
@item @i{White Rabbit Switch: Startup Guide}: hardware installation
instructions. This manual is provided by the manufacturer: it describes
handling measures, the external connectors, hardware features and the
initial bring-up of the device.
@item @i{White Rabbit Switch: User's Manual}: documentation about
configuring the @sc{wrs}, at software level. This guide is maintained
by software developers. The manual describes
configuration in a deployed network, either as a standalone device or
as network-booted equipment. The guide also describes how to upgrade
the switch, because we'll release new official firmware images over
time, as new features are implemented.
@item @i{White Rabbit Switch: Developer's Manual}: it describes the
build procedure and how internals work; use of scripts and
@sc{wrs}-specific programs etc. The manual is by developers
and for developers. This is the
document to check if you need to customize your @i{wrs} rebuild
software from new repository commits that are not an official release
point, or just install your @i{wrs} with custom configuration values.
@item @i{White Rabbit Switch: Failures and Diagnostics}: describes various
failure scenarios of a switch and ways how to recognize them.
Additionally, it describes SNMP exports of a switch (@t{WR-SWITCH-MIB}).
The official @sc{pdf} copy of these manuals at each release
is published in the @i{files} tab of the software project in @t{ohwr.org}:
(@url{http://www.ohwr.org/projects/wr-switch-sw/files}).
This doesn't apply to release v4.0 and earlier.
The source form of all four manuals is maintained in @t{wr-switch-sw/doc}.
Within the repository, three of them the @i{User's Manual},
the @i{Developer's Manual} and the @i{Failures and Diagnostics}
are always tracking the software commits, while the @i{Startup Guide} may not
be authoritative because it is bound to device shipping rather than software
development.
@c ==========================================================================
@node Supported Hardware Versions
@section Supported Hardware Versions
This document applies to versions 3.3 and 3.4 of the @sc{wrs}
device.
Very few specimens of @t{wrs} 3.0 though 3.2 were manufactured; if you
are the owner of one of them, please refer to version 3.3 of the
@i{wrs-build} document, that includes appendixes about using older
versions. As usual, it is in the @i{files} tab of @t{ohwr.org}.
V1 and V2 were development items, never shipped.
@c ##########################################################################
@node Upgrading WRS Software
@chapter Upgrading WRS Software
The @sc{wrs} is shipped with a current version of its software image,
which is sometimes called @i{firmware}.
If your devices are running a previous version of the software you may
want to upgrade, or you may want to replace the firmware images after
rebuilding your own, as explained in the @i{Developer's Manual}.
If you run version 4.1 or later please copy @t{wrs-firmware.tar} file into
the @t{/update} partition via @t{scp} or web-interface and restart your switch.
When the running version during the update is at least v5.0, then update script
performs the check of md5 sums of all files inside the @t{wrs-firmware.tar}.
If at least one checksum is incorrect, the update is aborted and an error is
reported via SNMP (object @t{wrsFwUpdateStatus}) until the next successful update.
Additionally, the @t{wrs-firmware.tar} containing corrupted file is renamed to
@t{wrs-firmware.tar.checksum_error}. This file is automatically removed during
the next successful update.
When checksums in the @t{wrs-firmware.tar} are not available
(for example during downgrading to version pre-5.0) appropriate warning
message is printed to the console.
If this method of upgrading firmware works for you, you can ignore the rest of
this chapter, which
explains a transition between the initial way we passed MAC addresses
and the safer approach we introduced in v4.1
@c ==========================================================================
@node Upgrade from pre-v5.0 to v5.0
@section Upgrade from pre-v5.0 to v5.0
During the update from the pre-v5.0 firmware to v5.0 (or later) you might see
the following errors on the console.
@example
/wr/bin/sdb-read: can't load library 'libm.so.1'
Creating SDB filesystem in /dev/mtd5
cp: can't stat '/wr/etc/sdb-for-dataflash': No such file or directory
done
@end example
Please ignore this message, no real error occurred nor @i{hwinfo} partition
(@t{/dev/mtd5}) was overwritten. The error is caused by an old firmware trying
to run a binary (@t{sdb-read} to be precise) from the new firmware image.
The problem became visible now, because between v4.2 and v5.0 we uplifted
the buildroot, which changed the version of @t{libm} library from @t{libm.so.0}
to @t{libm.so.1}.
@c ==========================================================================
@node hwinfo for pre-v4.1
@section hwinfo for pre-v4.1
Version 4.1 (October 2014) and later ones use a new way to pass
hardware information to all levels of software, such information
includes the MAC addresses for the management Ethernet and the
@sc{sfp} ports. Information is now stored in a Flash partition called
@i{hwinfo}, using the @sc{sdb} file format. @sc{sdb} is defined in the
@t{fpga-configuration-space} within @t{ohwr.org}. Before using
@sc{sdb} we used to edit the boot loader's configuration at flash
The @i{hwinfo} structure is written to @i{dataflash} by the manufacturer. It is
never changed even when performing a complete re-flash of the device, because
the flashing scripts preserve the @i{hwinfo} memory area.
When upgrading from a pre-4.1 switch software, you need to create this
@i{hwinfo} data structure. The procedure is mostly automatic, but you
need to be aware of the steps involved, in case something goes wrong.
@c ==========================================================================
@node Upgrading from v4.0
@section Upgrading from v4.0
Version 4.0 and later of @t{wr-switch-sw} are able to upgrade
themselves if you place the proper files in the @i{/update} directory
of the @sc{wrs}. However, in version 4.0 we forgot to provide for
an upgrade of the boot loader and didn't note that if the front USB
cable is not plugged, the upgrade procedure blocks.
This latter problem happens because messages are written to the
management USB port, to help people flashing from scratch, and the
write is a blocking one by default: if nobody collects the USB data,
the system waits for a recipient. With version 4.1.1 the problem was fixed using
non-blocking operations (it is better to loose messages than to block the
installation because nobody is reading).
Thus, there are two different ways to upgrade; which one
you prefer we can't tell. Both work, each with its own drawbacks.
Each of them preserves the current MAC addresses.
@c =-------------------------------------------------------------------------
@node Upgrading from v4.0 with the USB cable
@subsection Upgrading from v4.0 with the USB cable
This is the procedure if you are able to walk to your @sc{wrs} and
connect to the management USB port, even if the port is not
actually used:
@item Copy your own @t{wrs-firmware.tar} for at least v4.1 into the
@i{/update} partition.
This can be the official firmware or one you built yourself.
Then reboot and wait for everything to settle (the system will reboot
once more by itself).
@item Copy @t{wrs-firmware.tar} again. And reboot again. The system
will reboot once more by itself.
@item Now you have a running updated version with your @i{hwinfo} in place
and the old MAC addresses preserved.
@end itemize
We save you from the long description of what is happening in the
various steps. If needed, it is in the @i{git} history of @t{wr-switch-sw},
at release point @t{v4.1}.
@c =-------------------------------------------------------------------------
@node Upgrading from v4.0 remotely
@subsection Upgrading from v4.0 remotely
If you can't walk to the switch, the procedure is faster but more
commands need to be typed on the root shell of the switch. We
support a single upgrade provided you change the kernel and initial
filesystem before rebooting.
@item Copy your own @t{wrs-firmware.tar} for at least v4.1 into the
@i{/update} partition. This can be the official firmware or one you built
@item Create and mount @i{/boot} within the switch. This means
running the following commands in @i{ssh}:
@t{mkdir /boot}
@t{mount -t ubifs ubi0:boot /boot}
@item Copy @t{wrs-initramfs.gz} (which is to be found inside
@t{wrs-firmware.tar}) to the @i{/boot} partition just mounted. This
ensures the new upgrade procedure will run, the one that doesn't block
if the USB cable is unplugged.
@item Copy @t{zImage} (again, to be found inside
@t{wrs-firmware.tar}) to the @i{/boot} partition. This is need to
be able to access the @i{hwinfo} partition at next boot.
@item Reboot and wait for everything to settle (the system will reboot
once more by itself after upgrading everything). The MAC addresses
will be saved to @i{hwinfo} during the update procedure, thanks to
the new kernel and new boot procedure you manually copied to @i{/boot}.
@b{Note:} if you forget to place the new kernel or @t{wrs-initramfs.gz}
in @i{/boot}, no big damage will happen, but you'll have lost your
MAC address for the @sc{wr} ports. You'll find a randomly-chosen value,
that will however be persistent over reboot (because it is saved to
@i{hwinfo} after you boot with the new kernel.
@c ==========================================================================
@node Upgrading from v3.x
@section Upgrading from v3.x
Upgrading from versions older than v4.0 (August 2014) requires physical
access to the device and, unfortunately, requires some extra steps
especially if you want to preserve your MAC addresses.
One possible path is flashing version 4.0 (please refer to v4.0
manuals) and then proceed as described in @ref{Upgrading from v4.0}.
When flashing version 4.0 you'll need to pass your MAC addresses on
the command line of the flasher, so please take note of what they are.
Another option is flashing the latest firmware version and then build
your own @i{hwinfo} structure by specifying your MAC addresses.
@t{wr-switch-sw} includes specific tools for both steps. They are
described in the @i{Developer's Manual}, because they are expected to
only be performed by the manufacturer, not the final user.
@c ##########################################################################
@node Configuration of the Device
@chapter Configuration of the Device
After release v3.3 of this software package, we added Kconfig support
to wr-switch-sw. If you build your software image (as documented
in the @i{@sc{wrs} Developer's Manual}), you can make some
configuration choices for your customized firmware image. But most
users are not expected to rebuild.
After release v4.1, we moved most of the configuration to run-time
(rather than build-time): the @t{.config} file that you create
with a ``@t{make menuconfig}'' or equivalent command, is now copied
to the @sc{wrs} filesystem and used during boot. Moreover, the
switch can download a new configuration at boot time, if so
configured. This allows customization of each installed switch
through a central server, without modifying the filesystem image in
each specimen.
Starting with release v4.2, we added ``@t{make config}'' support at run
time, to be run in @t{/wr/etc}; the file is called @t{dot-config}, and
not @t{.config}. This is meant to be useful for developers, when
testing different configurations in the lab, rather than in
production. We also support ``@t{make config}'', ``@t{make
defconfig}'', @t{make oldconfig}'', from v5.0 ``@t{make menuconfig}''
and ``@t{make nconfig}''.
@c ==========================================================================
@node Dynamic WRS Configuration
@section Dynamic WRS Configuration
The switch can boot using its internal @sc{nand} memory or as an NFS-Root
host. In the latter case configuration can be changed on the server,
and if a unit is replaced, a change in the @sc{dhcp} database is all
that's needed to recover network operation. But this option implies
some network traffic on your management network, as well as an NFS
server able to host all of your switches.
When a switch is booted from internal storage, we used to rely on
internal configuration (either selected at build time or modified
using @i{ssh} or the web interface). This approach doesn't scale
well to large installation, because if a device needs to be replaced,
its own configuration is lost.
With @i{dynamic configuration}, each @sc{wrs} device loads its own
configuration file each time it is booted, and applies the choices
before starting any service. The name of the configuration file can
include the @sc{mac}, @sc{ip} address or @sc{hostname} of the device, to allow
running several switches with different configurations in the same
network. The location of the configuration file can be stored in the
@t{dot-config} or be retrieved from DHCP server.
@c ==========================================================================
@node The Configuration File
@section The Configuration File
The main configuration file for the @sc{wrs} is
@t{/wr/etc/dot-config}. You create this file by running ``@t{make
menuconfig}'' within @t{wr-switch-sw} repo, and making your choices.
You can also edit the text file, or run other configurators: @t{make config},
@t{make xconfig}, @t{make gconfig}, @t{make nconfig}.
The configuration step creates @t{.config}, that you can copy to your
@sc{wrs} as @t{/wr/etc/dot-config}. After reboot, you'll see your
choices in effect.
The first configuration choice is about source of the @t{dot-config} file
(items starting with @t{CONFIG_DOTCONF_SOURCE_}). The following @t{dot-config}
sources are implemented in current version:
@table @t
@item CONFIG_DOTCONF_SOURCE_LOCAL
Use local @t{dot-config} file stored in @t{/wr/etc/dot-config}.
In this case no network access is performed.
@item CONFIG_DOTCONF_SOURCE_REMOTE
Get a @t{dot-config} file from the URL provided in @t{CONFIG_DOTCONF_URL}.
@item CONFIG_DOTCONF_SOURCE_FORCE_DHCP
Get a network location of a @t{dot-config} file from a DHCP server.
Server can be configured in a way to provide the entire URL to
the @t{dot-config} in the ``@t{filename}'' configuration field of the
DHCP server. In this case, provided URL has to be in the same form
as @t{CONFIG_DOTCONF_URL}.
As an alternative, ``@t{filename}'' can be configured only as a
path. It will be then interpreted as a path on a TFTP server, which IP
address is taken from the configuration field
``@t{The BOOTP next server option}'' of a DHCP server.
@item CONFIG_DOTCONF_SOURCE_TRY_DHCP
The same as @t{CONFIG_DOTCONF_SOURCE_FORCE_DHCP}, but this option does
not cause errors in SNMP's objects if switch fails to retrieve the
URL to the @t{dot-config} via DHCP. Note that syntax and download
errors of @t{dot-config} are notified in the same way as for other
choices.
@end table
If the selected option triggers @sc{wrs} to download a new @t{dot-config}
file and it passes the validation process, the new @t{dot-config} will replace
a local copy. In case there are errors or unknown
configuration entries in the retrieved file, the old one will be used.
The URL (stored in @t{CONFIG_DOTCONF_URL} or retrieved via DHCP) is of the form
``@i{protocol}@t{://}@i{host}@t{/}@i{pathname}''. The special upper-case
strings @t{HOSTNAME}, @t{IPADDR} and @t{MACADDR} are substituted with the
current hostname, IP address or MAC address of the management port of the
switch. By this, the same configuration string can be used to set up a batch
of switches with different configurations.
The three parts of the URL are as follows:
@table @i
@item protocol
We support @t{http}, @t{ftp} and @t{tftp}. Any other protocols
result in an error, and the @t{dot-config} file is not replaced.
The host can be an IP address, or a name. In order to use
a name you must specify a valid @t{CONFIG_DNS_SERVER} and
optionally @t{CONFIG_DNS_DOMAIN}. Alternatively DNS configuration can
be taken from the DHCP server. The values
in the current @t{dot-config} are used to load the new file.
@item path
The pathname can include directory components and any of @t{HOSTNAME},
@t{IPADDR}, @t{MACADDR}.
@end table
For example this is a valid configuration for run-time update:
@smallexample
CONFIG_DOTCONF_SOURCE_REMOTE=y
CONFIG_DOTCONF_URL="tftp://morgana/wrs-config-IPADDR"
CONFIG_DNS_SERVER="192.168.16.1"
CONFIG_DNS_DOMAIN="i.gnudd.com"
@end smallexample
It results in @t{wrs-config-192.168.16.9} being served to the @sc{wrs}.
Please remember, that the new @t{dot-config} should include a valid
@t{CONFIG_DOTCONF_SOURCE_*} setting, or you won't be able to update the
configuration at the next boot. In any case, you can always copy a
configuration file using @i{ssh}, or use the web interface to change the
configuration.
Changes performed using the web interface are immediately active, because
the web server takes proper action; the new file copied over with @i{ssh},
or any hand-edits, are only effective at next boot, unless overwritten by
a remote configuration file.
In case there are errors or unknown configuration entries in the retrieved
file, the old one will be used.
@c ==========================================================================
@node Configuration Items that Apply at Build Time
@section Configuration Items that Apply at Build Time
The following items in @t{dot-config} are used at build time; changing
them in the installed version has no effect:
@table @code
@item CONFIG_BR2_CONFIGFILE
This string option lists a file to be used as Buildroot (BR2)
configuration. A simple filename or relative pathname refers to the
@t{configs/buildroot} directory; an absolute pathname is used
unchanged.
@item CONFIG_KEEP_ROOTFS
A boolean option for developers: if set the build script does
not delete the temporary copy of the generated filesystem and
reports its pathname in the build messages.
@end table
@c ==========================================================================
@node Configuration Items that Apply at Run Time
@section Configuration Items that Apply at Run Time
The following items in @t{dot-config} are used at run time: at every
boot the value (the old one or the just-downloaded one) is used in the
appropriate way, before the respective service is started.
@c When the value is changed by the web interface, proper action is taken.
@item CONFIG_DOTCONF_SOURCE_LOCAL
@itemx CONFIG_DOTCONF_SOURCE_REMOTE
@itemx CONFIG_DOTCONF_SOURCE_FORCE_DHCP
@itemx CONFIG_DOTCONF_SOURCE_TRY_DHCP
@itemx CONFIG_DOTCONF_URL
The source and location of a config file to be used at a replacement
the next time the system boots. See @ref{Dynamic WRS Configuration}
and @ref{The Configuration File} for details.
@item CONFIG_ETH0_DHCP
@itemx CONFIG_ETH0_DHCP_ONCE
@itemx CONFIG_ETH0_STATIC
Configuration of management port's (@t{eth0}) IP. When
@t{CONFIG_ETH0_DHCP} is used, then switch tries to obtain IP via DHCP
forever. For option @t{CONFIG_ETH0_DHCP_ONCE} switch tries to get IP
via DHCP once, if this try is unsuccessful then switch uses static IP.
@t{CONFIG_ETH0_STATIC} forces switch to use provided static IP address.
@item CONFIG_ETH0_IP
@itemx CONFIG_ETH0_MASK
@itemx CONFIG_ETH0_NETWORK
@itemx CONFIG_ETH0_BROADCAST
@itemx CONFIG_ETH0_GATEWAY
Management port's (@t{eth0}) static IP configuration when
@t{CONFIG_ETH0_DHCP_ONCE} or @t{CONFIG_ETH0_STATIC} parameter is used.
@item CONFIG_HOSTNAME_DHCP
@itemx CONFIG_HOSTNAME_STATIC
@itemx CONFIG_HOSTNAME_STRING
These options describe how to set hostname of the switch. From DHCP
(@t{CONFIG_HOSTNAME_DHCP}) or use a predefined value
(@t{CONFIG_HOSTNAME_STATIC}) defined in option @t{CONFIG_HOSTNAME_STRING}.
@item CONFIG_ROOT_PWD_IS_ENCRYPTED
@itemx CONFIG_ROOT_PWD_CLEAR
@itemx CONFIG_ROOT_PWD_CYPHER
This set of options allow setting the password for the ``root''
user (the administrator). The password is used to login to
your switch using @t{ssh} (secure shell). If you choose
@t{CONFIG_ROOT_PWD_IS_ENCRYPTED}, you will be prompted for a
text version of a pre-encrypted password (@t{CONFIG_ROOT_PWD_CYPHER}).
To encrypt your @i{magic} string, you must run ``@t{mkpasswd
--method=md5} @i{magic}'' on your Linux host (or switch).
If you choose to configure an unencrypted password, then you are
asked to specify it as @t{CONFIG_ROOT_PWD_CLEAR}. In this latter
case encryption is performed at run-time to use the normal @i{ssh}
authentication, but the clear-text password will remain in
@t{dot-config}.
By default the root password is an empty string, like in the initial
@i{wr-switch-sw} releases.
@item CONFIG_NTP_SERVER
The NTP server used to prime White Rabbit time, at system boot.
The option can be an IP address or a host name, if DNS is properly
configured. The configuration value is stored in
@t{/etc/wr_date.conf}. An empty string (default) disables
NTP access at boot time.
@item CONFIG_DNS_SERVER
@itemx CONFIG_DNS_DOMAIN
The DNS server (as an IP address) and default domain. The values
end up in @t{/etc/resolv.conf} of the runtime filesystem.
By default the two strings are empty. If @t{CONFIG_ETH0_DHCP} or
@t{CONFIG_ETH0_DHCP_ONCE} is used, @t{/etc/resolv.conf} file will be
populated with DNS settings received from the DHCP server.
If configuration items for static (@t{CONFIG_DNS_*}) and dynamic
(@t{CONFIG_ETH0_DHCP}) DNS configuration are used simultaneously
then information from both sources end up in the @t{/etc/resolv.conf}
file. However, information from @t{CONFIG_DNS_*} is placed first.
@item CONFIG_REMOTE_SYSLOG_SERVER
@itemx CONFIG_REMOTE_SYSLOG_UDP
Configuration for system log. The name (or IP address) of the
server is stored in @t{/etc/rsyslog.conf} of the runtime
filesystem. The UDP option, set by default, chooses UDP transmission;
if unset it selects TCP communication.
@item CONFIG_WRS_LOG_HAL
@itemx CONFIG_WRS_LOG_RTU
@itemx CONFIG_WRS_LOG_PTP
@itemx CONFIG_WRS_LOG_OTHER
Logging options for the three main WRS processes and other programs.
@t{CONFIG_WRS_LOG_OTHER} is currently used by:
@itemize
@item @t{wrs_watchdog} daemon
@item @t{wrs_throttling} executed once at boot up
@item @t{wrs_auxclk} executed once at boot up
@item @t{wrs_custom_boot_script.sh} executed once at boot up
@item Setting VLANs with @t{vlan.sh} at boot up
@end itemize
Each value
can be a pathname, either to a file (e.g. @t{/dev/kmsg}
is a possible ``file'' target) or a @i{facility}.@i{level} string,
like @t{daemon.debug}, for syslog-based logging.
An empty strings selects no logging at all. Please note, that
unknown facility names will generate a runtime error on the switch.
All four strings default to ``@t{daemon.info}''.
@item CONFIG_WRS_LOG_SNMPD
Value can be a pathname, either to a file (e.g.
@t{/dev/kmsg} is a possible ``file'' target) or a valid snmpd log
option (without -L).
Allowed strings are in the format ``@t{S} @i{level} @i{facility}'' (e.g.
``@t{S 2 daemon}''). For example, ``@t{s daemon}'' will forward
messages to syslog with daemon as facility. To set level (i.e. 5) use
``@t{S 5 daemon}''. For details please check @t{man snmpcmd}. An empty
strings selects no logging at all. Please note that unknown facility
names will generate a runtime error on the switch. NOTE: It looks
like @t{Notice} is not a default logging priority as written in
@i{net-snmp} manual.
@item CONFIG_WRS_LOG_MONIT
The string can be a pathname (e.g. @t{/dev/kmsg}) or a @t{syslog}
string.
An empty string is used to represent no logging. If it is needed to
select facility and level please leave an empty string here and change
@t{/etc/monitrc} or @t{/usr/etc/monitrc} file directly.
Please note that unknown facility names will generate a runtime error
on the switch.
@item CONFIG_PORT01_PARAMS
@itemx CONFIG_PORT02_PARAMS
@itemx CONFIG_PORT18_PARAMS
These configuration items are used to set up timing parameters of the
WR ports:
@itemize
@item @t{name} -- the name of a given interface
@item @t{proto} -- PTP protocol type to be used on particular
port; possible values:
@itemize
@item @t{raw} -- use raw Ethernet frames for timing
@item @t{udp} -- use UDP packets for timing
@end itemize
@item @t{tx} -- TX delay of a port in picoseconds
@item @t{rx} -- RX delay of a port in picoseconds
@item @t{role} -- PTP role of a port; possible values:
@itemize
@item @t{master} -- configure port as WR master
@item @t{slave} -- configure port as WR slave
@item @t{auto} -- when a port is connected to master
behave as a slave, otherwise behave
as master
@item @t{non-wr} -- for this port don't report SNMP
errors like: SFP not in DB,
copper SFP connected, non 1GB
SFP etc. This role should be used
for synchronizing regular IEEE-1588
slaves.
@item @t{none} -- disable White Rabbit and PTP on a
port
@end itemize
@item @t{fiber} -- fiber index from @t{CONFIG_FIBERXX_PARAMS}
that is connected to this port
@end itemize
Most likely the default values work for you.
See @ref{Timing Configuration} for details.
@item CONFIG_SFP00_PARAMS
@itemx ...
@itemx CONFIG_SFP09_PARAMS
Configuration for @sc{sfp} models. You should fill
all @sc{sfp} models and all
wavelengths you are using in your @sc{wrs}
@itemize
@item @t{vn} (@i{optional}) -- Vendor Name of an SFP
@item @t{pn} -- Part Number of an SFP
@item @t{vs} (@i{optional}) -- Vendor Serial (serial number) of
an SFP
@item @t{tx} -- TX delay of an SFP in picoseconds
@item @t{rx} -- RX delay of an SFP in picoseconds
@item @t{wl_txrx} -- Tx wavelength separated by "+" with Rx
wavelength of an SFP;
for example @t{wl_txrx=1490+1310} (for
1490nm Tx wavelength and 1310nm Rx
wavelength)
@end itemize
See @ref{Timing Configuration} for details.
@item CONFIG_FIBER00_PARAMS
@itemx ...
@itemx CONFIG_FIBER03_PARAMS
This parameter specifies the physical features of used fiber types.
Specify the alpha value for each pair of used wavelengths.
This parameter follows a format:
@t{alpha_XXXX_YYYY=1.23e-04,alpha_AAAA_BBBB=4.56e-04,...}
Where:
@itemize
@item @t{XXX_YYYY} and @t{AAAA_BBBB} are pairs of used wavelengths
@item @t{1.23e-04} and @t{4.56e-04} are alpha values to be used for
particular wavelengths.
@end itemize
The index (@t{00} onwards) is used to match the port
(@t{CONFIG_PORTxx_PARAMS}) with one of several installed fiber types.
See @ref{Timing Configuration} for details.
You are expected to have no more than 4 fiber types installed in
your deployment.
@item CONFIG_TIME_GM
@itemx CONFIG_TIME_FM
@itemx CONFIG_TIME_BC
The type of PTP clock this switch is. Only one of the three
items should be set (e.g. running ``@t{make menuconfig}'' offers
them as an exclusive choice). The options select: a grand-master (GM)
with external reference, e.g. GPS or Cesium; a free-running
master (FM), used for isolated acquisition networks, without an
external reference; or a normal ``boundary-clock'' (BC) device that
is slave on some ports and master on other ports.
@item CONFIG_PTP_PORT_PARAMS
@itemx CONFIG_PTP_CUSTOM
@itemx CONFIG_PTP_REMOTE_CONF
By default, PTP daemon (PPSi) configuration file is assembled based on role and
protocol parameters stored in @t{PORTxx_PARAMS}. If VLANs are
configured, the items
@t{CONFIG_VLANS_PORTXX_VID} are used as well.
Parameters @t{clock-class} and @t{clock-accuracy} can be changed
or new global PPSi settings can be added by editing file
@t{/wr/etc/ppsi-pre.conf}, which is used as beginning of final
PPSi configuration file.
Alternatively, PPSi can use a custom user file for configuration
(@t{CONFIG_PTP_CUSTOM}).
Finally, you can choose @t{PTP_REMOTE_CONF} to
specify an URL whence the switch will download the @t{ppsi.conf} at
boot time.
Please see the help provided within @i{Kconfig} for more details about
the various options we support.
@item CONFIG_PTP_CUSTOM_FILENAME
If you chose @t{CONFIG_PTP_CUSTOM} in the choice above, you
can provide your own filename for the PPSi configuration file;
the chosen name is expected to be installed in the @sc{wrs}
filesystem.
@item CONFIG_PTP_CONF_URL
If you choose @t{CONFIG_PTP_REMOTE_CONF} specify an URL
(@t{http://}, @t{ftp://} or @t{tftp://}) whence
the switch will download the @t{ppsi.conf} at boot time.
The filename in the URL can include @t{HOSTNAME}, @t{IPADDR}
and/or @t{MACADDR}, so the same configuration string can be used to set
up a batch of switches with different configurations (similar to the
@t{CONFIG_DOTCONF_URL}, please refer to @ref{The Configuration File}).
@item CONFIG_SNMP_TRAPSINK_ADDRESS
@itemx CONFIG_SNMP_TRAP2SINK_ADDRESS
@itemx CONFIG_SNMP_RO_COMMUNITY
@itemx CONFIG_SNMP_RW_COMMUNITY
Configuration for the @sc{snmp} agent. Addresses can be IP addresses
or names (if DNS is configured and working), they are unset by
default. Community values are strings and they default to
@t{public} (@t{RO_COMMUNITY}) and @t{private} (@t{RW_COMMUNITY}).
@item CONFIG_SNMP_TEMP_THOLD_FPGA
@itemx CONFIG_SNMP_TEMP_THOLD_PLL
@itemx CONFIG_SNMP_TEMP_THOLD_PSL
@itemx CONFIG_SNMP_TEMP_THOLD_PSR
Threshold levels for FPGA, PLL, Power Supply Left (PSL) and Power
Supply Right (PSR) temperature sensors. When any temperature exceeds
threshold level, SNMP object @t{WR-SWITCH-MIB::tempWarning} will change
accordingly.
@item CONFIG_SNMP_SWCORESTATUS_DISABLE
Force SNMP object @t{wrsSwcoreStatus} to be always OK. It can be used
to mask all potential problems with sw-core.
@c @item CONFIG_SNMP_SWCORESTATUS_HP_FRAME_RATE
@c
@c Error via SNMP if the rate of HP frames on any port exceed given value.
@c (currently not implemented)
@c@item CONFIG_SNMP_SWCORESTATUS_RX_FRAME_RATE
@c
@c Error via SNMP if rate of RX frames on any port exceed given value.
@c (currently not implemented)
@c@item CONFIG_SNMP_SWCORESTATUS_RX_PRIO_FRAME_RATE
@c
@c Error if frame rate of any RX priority exceed given value.
@c (currently not implemented)
@item CONFIG_WRSAUXCLK_FREQ
@itemx CONFIG_WRSAUXCLK_DUTY
@itemx CONFIG_WRSAUXCLK_CSHIFT
@itemx CONFIG_WRSAUXCLK_SIGDEL
@itemx CONFIG_WRSAUXCLK_PPSHIFT
Set of parameters passed to @t{wrs_auxclk} at boot time to generate
WR-synchronized 10MHz clock on the @i{clk2} output.
For more information please check @ref{wrs_auxclk}.
@item CONFIG_NIC_THROTTLING_ENABLED
@itemx CONFIG_NIC_THROTTLING_VAL
Limit the Rx bandwidth of the traffic that goes from WR ports to Linux.
Throttling can be enabled to prevent Linux using 100% of the processing
power to receive Ethernet frames coming from WR ports to the CPU.
To enable the throttling set @t{CONFIG_NIC_THROTTLING_ENABLED}.
@t{CONFIG_NIC_THROTTLING_VAL} contains maximum allowed bandwidth
in KB/s.
@item CONFIG_CUSTOM_BOOT_SCRIPT_ENABLED
@itemx CONFIG_CUSTOM_BOOT_SCRIPT_SOURCE_LOCAL
@itemx CONFIG_CUSTOM_BOOT_SCRIPT_SOURCE_REMOTE
@itemx CONFIG_CUSTOM_BOOT_SCRIPT_SOURCE_REMOTE_URL
It is possible to run a custom script at boot time. In this case please
set @t{CONFIG_CUSTOM_BOOT_SCRIPT_ENABLED}.
To run a script @t{/wr/bin/custom_boot_script.sh} from the local
filesystem please set @t{CONFIG_CUSTOM_BOOT_SCRIPT_SOURCE_LOCAL}.
As an alternative, you can choose
@t{CONFIG_CUSTOM_BOOT_SCRIPT_SOURCE_REMOTE} and specify an URL
(@t{http://}, @t{ftp://} or @t{tftp://}) in
@t{CONFIG_CUSTOM_BOOT_SCRIPT_SOURCE_REMOTE_URL} whence
the switch will download the script to be executed at boot time.
The filename in the URL can include @t{HOSTNAME}, @t{IPADDR}
and/or @t{MACADDR}, so the same configuration string can be used to set
up a batch of switches with different configurations (similar to the
@t{CONFIG_DOTCONF_URL}, please refer to @ref{The Configuration File}).
@item CONFIG_MONIT_DISABLE
Disable monitoring of running processes by @i{Monit}. @i{Monit} by
default
re-spawns processes that have died. This option should be used only during
development.
@item CONFIG_FAN_HYSTERESIS
@itemx CONFIG_FAN_HYSTERESIS_T_DISABLE
@itemx CONFIG_FAN_HYSTERESIS_T_ENABLE
@itemx CONFIG_FAN_HYSTERESIS_PWM_VAL
Use hysteresis to control fans. Enable fans with PWM value
@t{CONFIG_FAN_HYSTERESIS_PWM_VAL} when PLL's temperature exceeds
@t{CONFIG_FAN_HYSTERESIS_T_ENABLE}. Disable fans when temperature drops
below @t{CONFIG_FAN_HYSTERESIS_T_DISABLE}. These options are intended to
be used during development to reduce noise generated by a switch.
Don't use in production as this may affect the synchronization
performance.
@item CONFIG_READ_SFP_DIAG_ENABLE
Let HAL to read @i{Diagnostic Monitoring} (DOM) from SFP's eeprom,
like: temperature, TX/RX power etc.
@item CONFIG_RTU_HP_MASK_ENABLE
@itemx CONFIG_RTU_HP_MASK_VAL
Set the mask which VLAN priorities are considered High Priority traffic
(this
only concerns the traffic which is fast-forwarded).
To enable a custom mask please set
@t{CONFIG_RTU_HP_MASK_ENABLE}.
@t{CONFIG_RTU_HP_MASK_VAL} shall contain the mask to be used.
@item CONFIG_VLANS_ENABLE
Enable VLANs configuration. All below VLAN config options
(@t{CONFIG_VLANS_*}) require this filed to be set.
@item CONFIG_VLANS_PORTXX_MODE_ACCESS
@itemx CONFIG_VLANS_PORTXX_MODE_TRUNK
@itemx CONFIG_VLANS_PORTXX_MODE_DISABLED
@itemx CONFIG_VLANS_PORTXX_MODE_UNQUALIFIED
VLANs port mode configuration for ports 1..18.
It can be one of: Access, Trunk, Disabled or Unqualified.
For details please refer to the @ref{VLANs Configuration}
@item CONFIG_VLANS_PORTXX_UNTAG_ALL
@itemx CONFIG_VLANS_PORTXX_UNTAG_NONE
Define whether to remove a VLAN tag from egress frames on port 1..18.
@item CONFIG_VLANS_PORTXX_PRIO
Priority value used when tagging incoming frames or to locally override
the priority (in Unqualified and Disabled modes).
-1 disables the priority overwrite. Valid values are
from -1 to 7.
@item CONFIG_VLANS_PORTXX_VID
The meaning of this value and whether it is mandatory or optional,
depends on the port mode:
@itemize
@item @t{MODE_ACCESS} -- (mandatory) use as VID for tagging incoming
frames and notify PPSi which VLAN shall be used for
synchronization; only one VLAN number shall be used in this mode
@item @t{MODE_TRUNK} - (optional) notify PPSi which VLAN(s) shall
it use for synchronization; semicolon separated list is allowed
@item @t{MODE_DISABLED} - (optional) notify PPSi which VLAN(s)
shall it use for synchronization; semicolon separated list is allowed
@item @t{MODE_UNQUALIFIED} - (optional) notify PPSi which VLAN(s)
shall it use for synchronization; semicolon separated list is allowed
@end itemize
The range of a valid VID is from 0 to 4094.
@b{Note:} In firmware v5.0 it is not possible to set via
@t{dot-config} an override of VLAN tag for @t{UNQUALIFIED} mode.
For details please refer to the @ref{VLANs Configuration}
@item CONFIG_VLANS_VLANXXXX
Provide a configuration for VLAN from the range 0000-4094.
This option is a comma separated string in the following format:
@t{fid=<0..4094>,prio=<-1|0..7>,drop=<y|n>,ports=<1;2;...;...-...;18>}
Where:
@itemize
@item @t{fid} is a associated Filtering ID (FID) number. This parameter
may be useful for complex VLAN configurations. In simple cases it can
be omitted. One FID can be
associated with many VIDs. RTU learning is performed per-FID.
Associating many VIDs with a single FID allowed shared-VLANs
learning.
@item @t{prio} is a priority of a VLAN; can take values between -1 and
7;
-1 disables priority override, any other valid number takes
precedence over the port priority
@item If @t{drop} is set to @t{y}, @t{yes} or @t{1}, all frames
belonging to this VID are dropped (note that frame can belong to a
VID as a consequence of per-port Endpoint configuration); can take
values @t{y}, @t{yes}, @t{1}, @t{n}, @t{no}, @t{0}
@item @t{ports} is a list of ports separated with a semicolon sign
(";"); ports ranges are supported (with a dash character)
@end itemize
Example:
@t{fid=4,prio=2,drop=n,ports=1;3-5;15}
It sets FID as 4, priority 2, don't drop frames belonging to this VLAN,
Grzegorz Daniluk
committed
assign ports 1, 3-5 and 15 to this VLAN.
Grzegorz Daniluk
committed
For more details about VLANs configuration please refer to the
@ref{VLANs Configuration}
@c ==========================================================================
@node Timing Configuration
@section Timing Configuration
This section describes how timing configuration works in the switch.
Please note that up to version 4.1 (included) of @t{wr-switch-sw} things
were different and not really documented.
Timing configuration now depends on three sets of @t{dot-config}
variables: per-port information, per-sfp information and fiber
description.
This is, for explanation's sake, an example of such items: