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 February 2020
@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.0
@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 A. Rubini, A. Wujek, B. Rat, F. Vaga, J-C. Bau ...
@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}:
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-@value{release_version}) 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 v@value{release_version}
@section Upgrade from pre-v5.0 to v@value{release_version}
During the update from the pre-v5.0 firmware to v@value{release_version} (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 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:
@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 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
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 three configuration items are free-text fields which are intended for
dot-config management purposed. As now (v@value{release_version}.@value{release_version_tiny}) these fields are not used for
any functionality on the switch.
@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.
@item CONFIG_DOTCONF_INFO
Free-text item to descibe additional information about dot-config.
@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 server. If the DHCP server is reachable
but switch fails to download @t{dot-config} file then it will
cause errors in SNMP's objects.
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 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}.
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
@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_LDAP} for Kerberos authentication.
For the later one it is obligatory to specify Kerberos Realm
@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 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
@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.
The file is rotated when reaching 1MB. 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 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}''.
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
@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 of 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
@item @t{DEBUG} or 7
@end itemize
Not supported levels are ceiled to the valid one.
By leaving this item empty, programs will use its default verbosity
level (@t{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 of verbosity of a message.
@item CONFIG_WRS_LOG_LEVEL_PTP
Specify verbosity of PPSi daemon as a string. This string will be
passed to the PPSI after @t{-d} parameter. Please refer to the PPSI's
documentation for more details.
By leaving this item empty, PPSi daemon will use its default
verbosity level.
@b{Note:} all messages produced by PPSi if syslog is
configured will be passed to the syslog at the same
configured @i{<facility>.<level>}, no matter of verbosity of a message.
@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_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 to use the local version,
if exists, of @t{/etc/leap-seconds.list} file.
@t{CONFIG_LEAPSEC_SOURCE_REMOTE_FORCE} and @t{CONFIG_LEAPSEC_SOURCE_REMOTE_TRY} choices are
acting in the same way. The @t{leap-seconds.list} is read remotely using the URL
defined in @t{CONFIG_LEAPSEC_URL} using the same format as @t{CONFIG_DOTCONF_URL}. If the
downloaded file is newer than the local @t{/etc/leap-seconds.list} file, it will replace it.
Unlike @t{CONFIG_LEAPSEC_SOURCE_REMOTE_FORCE}, @t{CONFIG_LEAPSEC_SOURCE_REMOTE_TRY} option does
not cause errors in SNMP's objects if switch fails to download the file.
@item CONFIG_PTP_OPT_EXT_PORT_CONFIG_ENABLED
@itemx CONFIG_PORT@i{xx}_@i{zz}
These configuration items are used to set up timing parameters of the
WR port.
Items build using the format @t{CONFIG_PORT@i{xx}_@i{zz}} are composed of :
@itemize
@item @i{xx} -- represent the port number ('01' to '18')
@item @i{yy} -- the item signification for the given port @i{xx}
@end itemize
Most likely the default values work for you.
See @ref{Timing Configuration} for details.
@item CONFIG_N_SFP_ENTRIES
@itemx CONFIG_SFP00_PARAMS
@itemx CONFIG_SFP17_PARAMS
Configuration for @sc{sfp} models.
@t{CONFIG_N_SFP_ENTRIES} indicates number of available SFP entries defined. Up to 18 SFPs
can be defined.
@t{CONFIG_SFP@i{xx}_PARAMS} with index @i{xx} in range 00 to 17, contains @sc{sfp} parameters.
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_N_FIBER_ENTRIES
@item CONFIG_FIBER00_PARAMS
@itemx ...
@itemx CONFIG_FIBER17_PARAMS
This parameter specifies the physical features of used fiber types.
@t{CONFIG_N_FIBER_ENTRIES} indicates number of available fiber type entries defined. Up to 18
different fiber types can be defined.
@t{CONFIG_FIBER@i{xx}_PARAMS} with index @i{xx} in range 00 to 17, specifies the alpha value for each pair of used wavelengths.
This parameter follows a format:
@t{alpha_@i{xxxx}_@i{yyyy}=1.23e-04,alpha_@i{aaaa}_@i{bbbb}=4.56e-04,...}
Where:
@itemize
@item @t{@i{xxxx}_@i{yyyy}} and @t{@i{aaaa}_@i{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 by the @t{CONFIG_PORT@i{xx}_FIBER} port parameter to
reference the connected fiber type. @xref{Timing Configuration}.
You are expected to have no more than 18 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 five first
items should be set (e.g. running ``@t{make menuconfig}'' offers
them as an exclusive choice). The options select:
@itemize
@item @t{CONFIG_TIME_GM} a grand-master with external reference, e.g. GPS or Cesium.
@item @t{CONFIG_TIME_ARB_GM} a arbitrary grand-master which designates
a clock that is synchronized to an application-specific source of time.
@item @t{CONFIG_TIME_FM} a free-running master (FM), used for isolated
acquisition networks, without an external reference.
@item @t{CONFIG_TIME_BC} a normal ``boundary-clock'' device that
is slave on some ports and master on other ports.
@item @t{CONFIG_TIME_CUSTOM} an option which leave the possibility to define freely the clock class.
@end itemize
@item CONFIG_PTP_OPT_CLOCK_CLASS
An attribute defining the TAI traceability, synchronization state and
expected performance of the time or frequency distributed by a
Boundary Clock or Ordinary Clock.
Its value can be set only if @t{CONFIG_TIME_CUSTOM} parameter is selected. The following table shows the default value
used depending on the timing mode ''@t{CONFIG_TIME_@i{xx}}'' choice:
@multitable @columnfractions .3 .4
@headitem Timing mode @tab CONFIG_PTP_OPT_CLOCK_CLASS
@item CONFIG_TIME_GM @tab 6
@item CONFIG_TIME_ARB_GM @tab 13
@item CONFIG_TIME_FM @tab 193
@item CONFIG_TIME_BC @tab 248
@end multitable
For more details please refer to the IEEE 1588-2008 standard.
@item CONFIG_PTP_OPT_CLOCK_ACCURACY
An attribute defining the accuracy of the Local Clock (e.g. local
oscillator) of a Boundary Clock or Ordinary Clock.
By default its value is set automatically according to the timing mode ''@t{CONFIG_TIME_@i{xx}}'' choice.
However a value can be manually set either the option @t{CONFIG_PTP_OPT_OVERWRITE_ATTRIBUTES} is set
or the timing mode ``@t{CONFIG_TIME_CUSTOM}`` is selected.
The following table gives the default values depending on the timing mode ''@t{CONFIG_TIME_@i{xx}}'' choice :
@multitable @columnfractions .3 .4
@headitem Timing mode @tab CONFIG_PTP_OPT_CLOCK_ACCURACY
@item CONFIG_TIME_GM @tab 33
@item CONFIG_TIME_ARB_GM @tab 33
@item CONFIG_TIME_FM @tab 32
@item CONFIG_TIME_BC @tab 254
@end multitable
For more details please refer to the IEEE 1588-2008 standard.
@item CONFIG_PTP_OPT_CLOCK_ALLAN_VARIANCE
An attribute defining the stability of the Local Clock of a
Boundary Clock or Ordinary Clock.
By default its value is set automatically according to the timing mode ''@t{CONFIG_TIME_@i{xx}}'' choice.
However a value can be manually set either the option @t{CONFIG_PTP_OPT_OVERWRITE_ATTRIBUTES} is set
or the timing mode ``@t{CONFIG_TIME_CUSTOM}`` is selected.
The following table gives the default values depending on the timing mode ''@t{CONFIG_TIME_@i{xx}}'' choice :
@multitable @columnfractions .3 .4
@headitem Timing mode @tab CONFIG_PTP_OPT_CLOCK_ALLAN_VARIANCE
@item CONFIG_TIME_GM @tab 47360
@item CONFIG_TIME_ARB_GM @tab 47360
@item CONFIG_TIME_FM @tab 50973
@item CONFIG_TIME_BC @tab 65535
@end multitable
For more details please refer to the IEEE 1588-2008 standard.
@item CONFIG_PTP_OPT_TIME_SOURCE
This information-only attribute indicates the source of time used
by the grandmaster (or free-running master).
The following table gives the default values depending on the timing mode ''@t{CONFIG_TIME_@i{xx}}'' choice :
@multitable @columnfractions .3 .4
@headitem Timing mode @tab CONFIG_PTP_OPT_TIME_SOURCE
@item CONFIG_TIME_GM @tab 32 (GNSS)
@item CONFIG_TIME_ARB_GM @tab 32 (GNSS)
@item CONFIG_TIME_FM @tab 160 (INTERNAL_OSCILLATOR)
@item CONFIG_TIME_BC @tab --
@end multitable
@item CONFIG_PTP_OPT_DOMAIN_NUMBER
A domain consists of one or more PTP devices communicating with each
other as defined by the PTP protocol. A domain defines the scope of
PTP message communication, state, operations, data sets, and
timescale. PTP devices may participate in multiple domains.
For more details please refer to the IEEE 1588-2008 standard.
@item CONFIG_PTP_OPT_PRIORITY1
A user configurable designation that a clock belongs to an ordered
set of PTP devices from which a PTP Master is selected.
For more details please refer to the IEEE 1588-2008 standard.
@item CONFIG_PTP_OPT_PRIORITY2
A user configurable designation that provides finer grained ordering
among otherwise equivalent PTP devices.
For more details please refer to the IEEE 1588-2008 standard.
@item CONFIG_PORT@i{xx}_@i{zz}
@itemx CONFIG_PTP_CUSTOM
@itemx CONFIG_PTP_REMOTE_CONF
By default, PTP daemon (PPSi) configuration file is assembled based on parameters stored
in @t{CONFIG_PORT@i{xx}_@i{zz}} parameters.
If VLANs are configured, the items @t{CONFIG_VLANS_PORT@i{xx}_VID} are used as well.
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_PPSGEN_PTP_FALLBACK
@itemx CONFIG_PPSGEN_PTP_THRESHOLD_MS
@itemx CONFIG_PPSGEN_GM_DELAY_TO_GEN_PPS_SEC
@itemx CONFIG_PPSGEN_FORCE
Configuration of the PPS output. By default, the PPS is generated on a grand master switch
only when the timing mode is set either to @t{CONFIG_TIMING_GM} or @t{CONFIG_TIME_FM}.
However the @t{CONFIG_PPSGEN_FORCE} option, if activated, leaves the possibility to force the PPS