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!)