wrs-user-manual.in

\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
@copying
Copyright CERN 2023.
This document is licensed under the Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license.
@end copying

@setchapternewpage off

@set update-month June 2023
@c the release name below is substituted at build time
@set release __RELEASE_GIT_ID__

@comment %**useful declaration used in the document
@set release_version 6.1
@set release_version_tiny 0
@set url_docs https://www.ohwr.org/project/wr-switch-sw/wikis/Documents#files

@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 J-C. Bau, G. Daniluk, M. Lipinski, B. Rat, A. Rubini,
@author F. Vaga, A. Wujek
@insertcopying
@end titlepage
@headings single

@c ##########################################################################
@iftex
@contents
@end iftex

@c ##########################################################################
@c Top node is not included in tex
@unnumbered 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}).

@item @i{White Rabbit Switch: Radius Vlan}: describes functionality and usage
   of Radius Vlan which is a subset of IEEE 802.1X.
   When a devices is detected on a configured port, a Radius server is queried
   for authorization.

@end itemize

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}:
(@uref{@value{url_docs}})).
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{@uref{@value{url_docs}}}.

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-v5.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 v6.0.x to v@value{release_version}
@section Upgrade from v6.0.x to v@value{release_version}

Apart from the instructions in the previous section, there
is no special action needed from the user when upgrading firmware from
v6.0.x to v@value{release_version}.

The most important changes introduced in v6.1 are:
@itemize
@item Display information about GrandMaster in @t{wr_mon}
@item Informing about unrecognized SFP in @t{wr_mon}
@item Improved reporting of offset between NTP and WR time via SNMP
@item Support of disabling SFP's TX laser with @t{wrs_sfp_dump}
@item Fixes in handling of SFP's diagnostics (if SFP diagnostic is used with
      firmware v6.0.x it can corrupt SFP's eeprom!)
@item Detection whether a switch is a low-jitter version (displayed in
      @t{wrs_version}, SNMP and web interface), and fix to leap-seconds.list update
@item Addition of a subset of IP-MIB, BRIDGE-MIB and QBRIDGE-MIB objects
      to SNMP support
@item Implementation of @t{sysObjectID} OID value to reflect WRS manufacturer and
      HW version
@item Implementation of radius-802.1X for MAC authentication (subset of IEEE 802.1X)
@item Support of LLDP with VLANs
@end itemize

The following configuration items were added to the dot-config:
@itemize
@item LLDP related
@itemize
@item @t{CONFIG_VLANS_PORT@i{xx}_LLDP_TX_VID}
@item @t{CONFIG_VLANS_PORT@i{xx}_LLDP_TX_PRIO}
@end itemize

@item Radius related:
@itemize
@item @t{CONFIG_RVLAN_ENABLE}
@item @t{CONFIG_RVLAN_PMASK}
@item @t{CONFIG_RVLAN_AUTH_VLAN}
@item @t{CONFIG_RVLAN_NOAUTH_VLAN}
@item @t{CONFIG_RVLAN_OBEY_DOTCONFIG}
@item @t{CONFIG_RVLAN_RADIUS_SERVERS}
@item @t{CONFIG_RVLAN_RADIUS_SECRET}
@end itemize

@item SNMP related:
@itemize
@item @t{CONFIG_SNMP_SYSCONTACT}
@item @t{CONFIG_SNMP_SYSLOCATION}
@end itemize

@item @t{CONFIG_PPSGEN_FR_ON_SYNC_ONLY}
@end itemize

Firmware v6.1 uses the same GW as v6.0.x, so the calibration values remain
the same.

Please note that Web interface remains disabled by default.

@c ==========================================================================
@node Upgrade from v5.0.1 to v6.0.x
@section Upgrade from v5.0.1 to v6.0.x

Apart from the instructions in the introduction to this chapter, there
is no special action needed from the user when upgrading firmware from
v5.0.1 to v6.0.x. Yet, special attention should be payed
to a number of improvements in configuration and slight changes in
the behavior of the WR Switch. Here are highlights:
@itemize

@item @b{IP address of the management port}

  WR switch running the default configuration file included in the v6.0 release
  will try to get dynamic IP address for the management port at boot time.
  In case the DHCP server is not responding, WR switch will use default static
  IP assignment:
  @smallexample
  IP address: 192.168.1.254
  Netmask:    255.255.255.0
  Network:    192.168.1.0
  Broadcast:  192.168.1.255
  Gateway:    192.168.1.1
  @end smallexample
  
@item @b{Low Phase Drift Calibration (LPDC)}

  Low Phase Drift Calibration is a new feature added in release v6.0 that
  improves phase stability between WR switch restarts to <10ps. Due to FPGA
  limitations this functionality is present only on ports 1-12. 
  The LPDC requires an additional, automated calibration procedure to run for Tx
  and Rx path of each affected FPGA transceiver. The Tx calibration is performed
  once for all ports at startup of the WR switch. The Rx calibration is performed
  each time a link goes up on a port. Both Tx and Rx calibration is indicated by
  blinking of @i{Link/WR Mode} LED (left).
  The downside is that the calibration makes startup of the WR switch longer.
  Similarly, the time between connecting a fiber and the link going up
  (e.g. as observed in @i{wr_mon}) is noticeably longer.

@item @b{Configuration of the WR switch} - while it was feasible to edit by
  hand the @i{dot-config} file in the pre-v6.0 firmware versions, it is
  highly discouraged now. Since the number of configuration options increased
  greatly, the @i{dot-config} file is very long and complex. Therefore,
  @b{it is highly recommended to use the menuconfig to generate the
  @i{dot-config}} (e.g.  @i{wrs_menuconfig} tool on the WR switch).
  Highlights of the changes to configuration are provided in the following 
  bullet points.

@item @b{Configuration of PTP/PPSi in menuconfig} - up to firmware
  v5.0.1, the configuration of PPSi in @i{menuconfig} was limited to a global timing
  mode (e.g. GM, BC) and per-port proto (raw, udp), rx/tx delays, role (e.g, 
  master, slave, auto) and fiber id. Any more complex configuration of PPSi had to
  be done via a custom @t{ppsi.conf} file and this was also limited. It was
  a known issue that the @i{auto} role that uses PTP's Best Master Clock
  Algorithm was not implemented correctly. We have updated PPSi fixing all known
  issues related to compliance with IEEE1588-2008 (PTPv2) and we have already
  introduced a number of new features from the IEEE1588-2019 (PTPv2.1) edition.
  This resulted in a substantial increase and reorganization of configuration 
  parameters for PPSi in @i{menuconfig} and @t{dot-config}.
  In short, the default
  behavior of Grand-Master, Free-Running Master and Boundary Clock are preserved,
  yet with different names for the configuration options which are compliant
  with the  IEEE1588-2019. Here are the highlights of the changes
  @itemize
  @item @b{Port Timing Configuration} is organized in per-port sub-menus 
    instead of a simple configuration strings. On each physical port,
    zero or one PTP Instance can configured (in future release we will allow more
    than one PTP Instance). If you do not want to use PTP on a given physical port,
    zero PTP Instances should be used. For each PTP Instance, a number of
    configuration parameters can be selected, including:
    @itemize
    @item @b{Network Protocol} - it allows to set PTP Mapping to 
      IEEE 802.3 or UPD/Ipv4, it used to be called @b{proto}
    @item @b{Delay Mechanism} - it allows to set E2P or P2P mechanism, previously
      possibly only via custom @t{ppsi.conf}
    @item @b{SNMP monitoring} - it can be disabled which was the case
      previously when @b{role} was set to @b{non-wr}
    @item @b{Profile} - it allows to chose between WR and standard PTP,
      the choice made previously via the @b{role} setting
    @item @b{Desired State} for BC or @b{BMCA mode} for GM - they replaces the
       @b{role} function for the Master/Slave/auto settings.
    @item @b{timestampCorrectionPortDS.egressLatency} - it replaces the @b{tx} delay
    @item @b{timestampCorrectionPortDS.ingressLatency} - it replaces the @b{rx} delay
    @item @b{externalPortConfigurationEnabled} - External Port Configuration is
      a new concept (optional feature) introduced in the IEEE1588-2019 (PTPv2.1)
      that legalizes what had been done in WR switches since long: manual
      assignment of the Master/Slave role per port. This option is used
      when a WR switch is set to @b{Boundary Clocks} Timing Mode. With this option
      enabled, the Best Master Clock Algorithm is disabled and each port must be
      assigned with the @b{Desired State}: Master/Slave/Passive. If External Port
      Configuration is disabled, the Best Master Clock Algorithm is used. Note
      that this option is global, i.e. it is not allowed to use it only on some
      ports.
    @item @b{MasterOnly} - MasterOnly is a new concept (optional feature) introduced
      in the IEEE1588-2019 (PTPv2.1) that legalizes per-port assignment of
      Master role, equivalent of setting role to be Master in the pre-v6.0 firmware.
      This assignment can be done on per-port basis and it coexists with the
      Best Master Clock Algorithm. This option is used when a WR switch is set
      to @b{Grand-Master}, @b{Free-Running Master}, or @b{Arbitrary Grand-Master}.
    @end itemize
  @item @b{PTP options} - it is a new sub-menu that allows to set a number
    of global PTP parameters which previously had to be modified by customizing
    @t{ppsi.conf} file. This include: domain, priority1, priority2, clockClass.
    While these parameters are pre-filled automatically depending on the Timing
    Mode, they can be overridden if need be.
  @item @b{Timing Mode} - setting timing mode provides default configuration for
    all the above-mentioned options such that the behavior of the WR switch is
    equivalent to the same Timing Mode in pre-v6.0 firmware versions. There are
    two new modes available now: @b{Arbitrary Grand-Master} and @b{Custom}. The
    @b{Arbitrary Grand-Master} mode is similar to @b{Grand-Master} but has 
    different clockClass and ARB timescale. The @b{Custom} allows full control
    over PTP settings, otherwise limited to options allowed for a given Timing
    Mode. 
  @end itemize
@item @b{Configuration of VLANs in menuconfig} - pre-v6.0 firmware provided
  limited/simplified VLAN per-port configuration that did not allow setting some
  less-common configurations, otherwise allowed by CLI (@i{wrsw_vlan}).
  As of v6.0 firmware, such more user-friendly setting is still provided by
  default, yet it can be extended by setting @b{Enable raw ports configuration}.
@item @b{New configuration options in menuconfig}
  @itemize
  @item @b{Source for a run-time replacement of leap seconds file} - the 
    leap seconds file can be now fetch from a server and updated in
    runtime.
  @item @b{PPS generation} - it is now possible to specify a number
    of aspects of the PPS generation, @b{the default configuration might be
    slightly different from the pre-v6.0 firmware}.
  @item @b{LLDP options} - it provides configuration of Link Layer Discovery
    Protocol (LLDP) which is now supported. It is enabled by default. @b{Note that
    LLDP sends Ethernet frames of approximately 200 bytes. In the worst-case,
    transmission of such frames can increase traffic latency by 0.8us
     @footnote{The maximum PTP frame size is 96 bytes which translates into 0.76us
     latency increase to the data traffic, in case the PTP frame is sent to a
     port at the same time as the data traffic frame is to be forwarded to
     this port. An additional 100 bytes of the LLDP 
     frame, translates into additional 0.8us latency introduced by protocol 
     frames.}.} If you
    do not use LLDP and latency is of concern, you should disable LLDP option.
    Alternatively consider use of the option to limit LLDP frame size to about 
    60-70 bytes.
  @item @b{Disable web interface} - web interface is now disabled by default
    @footnote{Actually, web interface is disabled by default from firmware
    v6.0.2.
    The documentation of v6.0 claimed that it was already disabled, but it was
    wrong.}
    and considered deprecated (no effort was put in making sure it works
    properly). @b{Users are strongly discouraged from using the web interface}.
    A number of serious security vulnerabilities were found in the web interface
    (including CVE-2023-22577).
    Please note that it is still possible to enable web interface in run-time.
    @b{Users are strongly discouraged from using the web interface}.
    In exceptional cases the use of web-interface can be limited to well
    controlled networks.
  @end itemize

@item @b{DHCP forever configuration in menuconfig} - this behavior can be set 
  for two parameters:
  @b{Management port configuration} and @b{Source for a run-time replacement
  of dot-config} (it is called @i{Force to get the URL to a dot-config via
  DHCP} in the second case). In case the DHCP server was not available, in 
  the pre-v6.0 firmware, the WR switch would start with local dot-config and
  no IP. As of v6.0, with these settings, the WR switch waits forever
  for the DHCP server to reply. This behavior was introduced to ensure that
  operational WR switches always boot with desired remote dot-config file.
  Even if, in case of a power cut, DHCP server takes longer to boot than a WR
  Switch. Unfortunately, the downside is that while waiting for the DHCP server,
  WR switch it is not accessible via
  the management port or management USB. The only way to stop the endless loop
  is to connect via the back USB (ARM Test) and follow the instructions, i.e.
  press Enter.

@item @b{Updated look of wr_mon} - this mostly commonly used Command Line 
  Interface tool in the WR switch has been updated to provide more information,
  here are the highlights:
    @itemize
    @item @b{Timing Mode}@footnote{@i{PLL mode} from firmware v6.1}
      indicates the current timing mode of the Soft PLL,
      it is not the intended @i{Timing Mode} configured in the @t{dot-config}
      file. So, a GM or BC switch will show the @b{Timing Mode} to be @i{FR}
      (free running) until it locks to the source of time, i.e. input 10MHz &
      1PPS or Slave port, respectively. 
    @item @b{PTP/EXT/PDETECT states} provides information about
      @itemize
      @item @b{PTP} - indicates the PTP state of a given port, as established
        by Best Master Clock Algorithm, or configured via External Port 
        Configuration. Note that ports which are down (not connected) are always
        placed in @i{DISABLED} state.
      @item @b{EXT} - indicates the state of the currently used extension,
        for v6.0 firmware, it is the state of the White Rabbit state machine
        (more extensions in future will be supported). In the pre-v6.0 firmware,
        the state of PTP or extension was provided in the @i{PTP state} column.
      @item @b{PDETECT} - indicates the state of a state machine that governs
        the detection of extensions. When a WR link is being established, it 
        shows @i{WA_MSG}, when it is successfully established, it shows
        @i{EXT_ON}
      @end itemize
    @item @b{Synchronization status} - most of the parameter names were replaced
      with their equivalents used in the IEEE1588 standard:
      @itemize
      @item @b{DelayMM} is the previously  @i{Round-trip time (mu)}
      @item @b{DelayMS} is the previously  @i{Master-slave delay}
      @item @b{delayAsymmetry} is the previously  @i{Total link asymmetry}
      @item @b{delayCoefficient} is the previously @i{alpha}
      @item @b{ingressLatency} is the previously @i{Slave PHY delay RX} without the bitslide
      @item @b{egressLatency}  @i{Slave PHY delay TX}
      @item @b{offsetFromMaster} is the previously @i{Clock offset}
      @item @b{semistaticLatency} is a new parameter that indicates the
            bitslide value
      @end itemize
    @end itemize
@end itemize

@c ==========================================================================
@node Upgrade from pre-v5.0 to v5.0.1 or later
@section Upgrade from pre-v5.0 to v5.0.1 or later

During the update from the pre-v5.0 firmware to v5.0.1 or later (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
time.

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 and later
@section Upgrading from v4.0 and later

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 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:

@itemize @bullet

   @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.

@itemize

   @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.

   @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}.

@end itemize

@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 and later}.
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

The switch can boot embedded Linux using its internal @sc{nand} memory or as an
NFS-Root host. In the latter case is especially useful for development, when
binaries of various software daemons might need to be updated regularly.
But this option implies
some network traffic on your management network, as well as an NFS
server able to host all of your switches.

The configuration of every @sc{wrs} is described in a Kconfig-generated file.
This configuration file can be found in the filesystem of @sc{wrs} under
@t{/wr/etc/dot-config}. The switch runs by default with a configuration
provided with the stable firmware release. If you are running a small WR
network, or just a single switch for lab tests, you can modify various
settings directly from the shell or web interface. After logging to @sc{wrs}
(e.g. using @t{ssh}) you can call ``@t{wrs_menuconfig}`` command
to modify the locally stored configuration file in a convenient way.
However, this approach doesn't scale well to large installations, because if a device
needs to be replaced, its own configuration is lost.

For operational networks, it is recommended to setup
a DHCP/TFTP server for central management of configuration files and to let @sc{wrs}
download its @t{dot-config} file at boot time. This also facilitates recovering a
@sc{wr} network in case of @sc{wrs} hardware failure. It takes only a change in
the DHCP database to boot new @sc{wrs} without losing the desired configuration.
In this case, 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 can create this file either by running ``@t{make
menuconfig}'' within the local clone of @t{wr-switch-sw} repo or directly in the
shell of your switch (e.g. through @t{ssh}), and making your choices.
You can also edit the text file using external tools, 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 rest of this section describes various options that are provided through the
configuration (@t{dot-config}) file.

@table @t

@item CONFIG_DOTCONF_FW_VERSION
@itemx CONFIG_DOTCONF_HW_VERSION

	Free-text items to describe switch's firmware
	@t{CONFIG_DOTCONF_FW_VERSION} and hardware
	@t{CONFIG_DOTCONF_HW_VERSION} version. Additionally, the default value
	of @t{CONFIG_DOTCONF_FW_VERSION} can be used as a version of a Kconfig
	file. These fields do not affect any functionality of the switch.

@item CONFIG_DOTCONF_INFO

	Free-text item to describe any additional information about dot-config.
  This field does not affect any functionality of the switch.

@end table

The next configuration item is a choice 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.
        
        If the DHCP service is not available at boot time, the switch will wait
        forever until it has obtained the DHCP lease from the server. If the DHCP server is reachable 
        but switch fails to download @t{dot-config} file, it will report appropriate error over SNMP.
         
        This choice is only available if CONFIG_ETH0_DHCP is chosen for network configuration. 
        

@item CONFIG_DOTCONF_SOURCE_TRY_DHCP
	The same as @t{CONFIG_DOTCONF_SOURCE_FORCE_DHCP}, but this option does
        not trigger 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, local @t{dot-config} 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.

@item host

	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 running switch 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.

@table @code

@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{Configuration of the Device}
        and @ref{The Configuration File} for details.

@item CONFIG_LEAPSEC_SOURCE_LOCAL
@itemx CONFIG_LEAPSEC_SOURCE_REMOTE_FORCE
@itemx CONFIG_LEAPSEC_SOURCE_REMOTE_TRY
@itemx CONFIG_LEAPSEC_URL
	The @t{/etc/leap-seconds.list} file is used to get the current TAI offset. @xref{wr_date}.
	The @t{CONFIG_LEAPSEC_SOURCE_LOCAL} choice forces the use the local leap seconds file that
  is stored locally on the switch (under @t{/etc/leap-seconds.list}). 
	
	@t{CONFIG_LEAPSEC_SOURCE_REMOTE_FORCE} and @t{CONFIG_LEAPSEC_SOURCE_REMOTE_TRY} provide
  similar functionality. In both cases the @t{leap-seconds.list} is downloaded at boot
  time using the URL defined in @t{CONFIG_LEAPSEC_URL}. The address is defined in the
  same format as @t{CONFIG_DOTCONF_URL}. If the downloaded file is newer than the
  local copy stored in @t{/etc/leap-seconds.list}, it is used to update the local
  copy.
  In case the @sc{wrs} is unable to fetch a leap seconds file from the provided location,
  using @t{CONFIG_LEAPSEC_SOURCE_REMOTE_FORCE} will result in an error generated through
  SNMP, while using @t{CONFIG_LEAPSEC_SOURCE_REMOTE_TRY} will suppress the alarm.

@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_ACCESS_DISABLE

	Disable root access via ssh. With this option enabled it is still
	possible to use sudo to get root privileges.

@item CONFIG_LDAP_ENABLE
@itemx CONFIG_LDAP_SERVER
@itemx CONFIG_LDAP_SEARCH_BASE
@itemx CONFIG_LDAP_FILTER_NONE
@itemx CONFIG_LDAP_FILTER_EGROUP
@itemx CONFIG_LDAP_FILTER_CUSTOM
@itemx CONFIG_LDAP_FILTER_EGROUP_STR
@itemx CONFIG_LDAP_FILTER_CUSTOM_STR

        Set of options related to providing an authorization via LDAP for ssh.
        To be able to use LDAP please enable an option @t{CONFIG_LDAP_ENABLE},
        provide LDAP server (@t{CONFIG_LDAP_SERVER}) and the search base
        (@t{CONFIG_LDAP_SEARCH_BASE}). It is possible to limit the access
        to a particular e-group used at CERN (@t{CONFIG_LDAP_FILTER_EGROUP}
        to enable and @t{CONFIG_LDAP_FILTER_EGROUP_STR} to provide
        the e-group's name) or to provide the custom filtering string
        (@t{CONFIG_LDAP_FILTER_CUSTOM} to enable and
        @t{CONFIG_LDAP_FILTER_CUSTOM_STR} to provide the filter).
        For more information please refer to the @i{Kconfig}'s help.


@item CONFIG_AUTH_LDAP
@itemx CONFIG_AUTH_KRB5
@itemx CONFIG_AUTH_KRB5_SERVER

        Choose the authentication method. @t{CONFIG_AUTH_LDAP} for LDAP
        authentication, @t{CONFIG_AUTH_KRB5} for Kerberos authentication.
        For the later one it is obligatory to specify Kerberos Realm
        in @t{CONFIG_AUTH_KRB5_SERVER}.

@item CONFIG_ROOT_PWD_IS_ENCRYPTED
@itemx CONFIG_ROOT_PWD_CLEAR
@itemx CONFIG_ROOT_PWD_CYPHER

	This set of options allows 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
@itemx CONFIG_LOCAL_SYSLOG_FILE
	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.
	    @t{CONFIG_LOCAL_SYSLOG_FILE} option indicates the file to which
      syslog messages will be stored in a local filesystem of the @sc{wrs}.
	The file is rotated when reaching 1MB. The rotation is done through 10
	indexed files @i{syslog}, @i{syslog.1-9}. By default these files are
	created in @i{/tmp} folder.
	If remote server is specified, the messages go to both, server and local file.

@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 string suppresses all logging for a given daemon.  Please note, that
        unknown facility names will generate a runtime error on the switch.
        All four strings default to ``@t{daemon.info}''.

	@b{Note:} all messages produced by these programs if syslog is
	configured will be passed to the syslog at the same
	configured @i{<facility>.<level>}, no matter the verbosity of a message.
	To change the verbosity of programs please use
	@t{CONFIG_WRS_LOG_LEVEL_*}.

@item CONFIG_WRS_LOG_LEVEL_HAL
@itemx CONFIG_WRS_LOG_LEVEL_RTU
@itemx CONFIG_WRS_LOG_LEVEL_OTHER

	Specify verbosity of programs as a string or number. The following
	levels are supported:
	@itemize
	@item @t{ALERT} or 1
	@item @t{ERROR} or 3
	@item @t{WARNING} or 4
	@item @t{INFO} or 6