Skip to content

W
White Rabbit Switch - Software
Commit 9a376bca authored by Alessandro Rubini's avatar Alessandro Rubini
Browse files
Options

doc: document the dot-config mechanism 

Signed-off-by: Alessandro Rubini's avatarAlessandro Rubini <rubini@gnudd.com>
parent ea8778f5
Hide whitespace changes
Inline Side-by-side
Showing with 167 additions and 58 deletions
Kconfig
View file @ 9a376bca
mainmenu "White Rabbit Switch configuration" mainmenu "White Rabbit Switch configuration"
config DOTCONF_URL
string "URL for a run-time replacement of dot-config"
help
The White Rabbit Switch is configured at run-time,
according to a dot-config .config file. The file
is the same .config you are defining now. If you
select an empty string, dot-config is not replaced
at run time. Otherwise, tftp://, ftp:// or http://
URLs are allowed. Names are allowed if you configured
a DNS server. The special strings IPADDR and MACADDR
are substituted before retrieving the file.
Example: "tftp://morgana/wrs-config-IPADDR"
config BR2_CONFIGFILE config BR2_CONFIGFILE
string "Configuration file for Buildroot" string "Configuration file for Buildroot"
default "wrs_release_br2_config" default "wrs_release_br2_config"
...@@ -21,20 +35,6 @@ config PPSI ...@@ -21,20 +35,6 @@ config PPSI
menu "Local configuration" menu "Local configuration"
config DOTCONF_URL
string "URL for a run-time replacement of dot-config"
help
The White Rabbit Switch is configured at run-time,
according to a dot-config .config file. The file
is the same .config you are defining now. If you
select an empty string, dot-config is not replaced
at run time. Otherwise, tftp://, ftp:// or http://
URLs are allowed. Names are allowed if you configured
a DNS server. The special strings IPADDR and MACADDR
are substituted before retrieving the file.
Example: "tftp//morgana/wrs-config-IPADDR"
config NTP_SERVER config NTP_SERVER
string "IP address of local NTP server (empty for none)" string "IP address of local NTP server (empty for none)"
help help
......
doc/wrs-developer-manual.in
View file @ 9a376bca
...@@ -177,12 +177,11 @@ After release 3.3, we decided to add @i{Kconfig} support. This means ...@@ -177,12 +177,11 @@ After release 3.3, we decided to add @i{Kconfig} support. This means
that the first build step is expected to be ``@t{make menuconfig}'', that the first build step is expected to be ``@t{make menuconfig}'',
like it happens for the kernel. The default configuration is selected like it happens for the kernel. The default configuration is selected
by default when one of the build scripts is run, so the procedure for by default when one of the build scripts is run, so the procedure for
the final user is the same as for v3.3 and earlier. A build with a the final user is the same as for v3.3 and earlier.
non-default configuration, however, is not considered as
``supported'', and @i{Kconfig} is there mainly to help developers try After release 4.1 we support dynamic reconfiguration. As opposed
new packages and setups without changing the repository or to build-time configuration, run-time configuration is expected to
introducing problems for other users. For some more information about be frequent, and it's thus documented in the @i{@sc{wrs} Users' Manual}.
@i{Kconfig} in this package, see the @i{@sc{wrs} User's Manual}.
The build system is set up as a mix of scripts and makefiles. Every The build system is set up as a mix of scripts and makefiles. Every
sub-package is built by its own script and/or Makefile, and configuration is sub-package is built by its own script and/or Makefile, and configuration is
...@@ -451,14 +450,9 @@ to be used at installation time. See @ref{Flashing Procedure} for details. ...@@ -451,14 +450,9 @@ to be used at installation time. See @ref{Flashing Procedure} for details.
Some details of the complete firmware archive depend on the values of Some details of the complete firmware archive depend on the values of
active @t{Kconfig} variables. If no manual configuration is performed, active @t{Kconfig} variables. If no manual configuration is performed,
what applies is @t{configs/wrs_release_defconfig}. what applies is @t{configs/wrs_release_defconfig}. Please note that
we now support dynamic reconfiguration at run-time. See the @i{@sc{wrs}
If you want to customize your configuration to install several Users' Manual}.
switches pre-configured for your network, we suggest you rebuild
the @i{firmware} archive after running @t{make menuconfig} to select
your own values
@c FIXME FIXME FIXME: Store kconfig and build info in the archive itself
@c -------------------------------------------------------------------------- @c --------------------------------------------------------------------------
@node Rebuilding Parts @node Rebuilding Parts
......
doc/wrs-user-manual.in
View file @ 9a376bca
...@@ -281,28 +281,121 @@ only be performed by the manufacturer, not the final user. ...@@ -281,28 +281,121 @@ only be performed by the manufacturer, not the final user.
@c ########################################################################## @c ##########################################################################
@node Kconfig Support @node Configuration of the Device
@chapter Kconfig Support @chapter Configuration of the Device
After release 3.3 of this software package, we added Kconfig support After release 3.3 of this software package, we added Kconfig support
to wr-switch-sw. The user can ignore this step: building as usual to wr-switch-sw. If you build your software image (as documented
from a fresh checkout of @t{wr-switch-sw} silently selects in the @i{@sc{wrs} Developer's Manual}), you can make some
the default configuration. configuration choices for your customized firmware image. But most
users are not expected to rebuild.
After release 4.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.
You may exploit this @t{Kconfig} option to build firmware images @c ==========================================================================
preconfigured for your own network. @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} or @sc{ip} address of the device, to allow
running several switches with different configurations in the same
network.
@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}, and making your choices.
You can also edit the text file, or run other configurators: @t{make xconfig},
@t{make gconfig}, @t{make config}.
The configuration step creates @t{.config}, that you can copy to your
@sc{wrs} as @t{/wr/etc/dot-config}. After reboot, you'll see your
choices in effect.
The first configuration choice is @t{CONFIG_DOTCONF_URL}. If the
selected string is not empty, the Switch will download a new @t{dot-config}
file, and replace the copy in local storage if it is different. If
the string is empty, no network access is performed.
@t{CONFIG_DOTCONF_URL} is of the form
``@i{protocol}@t{://}@i{host}@t{/}@i{pathname}''. The special upper-case
strings @t{IPADDR} and @t{MACADDR} are substituted with the current
addresses of the management port of the switch.
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}. The values
in the current @t{dot-config} are used to load the new file.
@item path
The pathname can include directory components and @t{IPADDR}
or @t{MACADDR} (or both).
@end table
For example this is a valid configuration for run-time update:
@smallexample
CONFIG_DOTCONF_URL="tftp://morgana/wrs-config-IPADDR"
CONFIG_DNS_SERVER="192.168.16.1"
CONFIG_DNS_DOMAIN="i.gnudd.com"
@end smallexample
And it results, in my case, in @t{wrs-config-192.168.16.9} being
served to the @sc{wrs}.
To change configuration, you are expected to run ``@t{make Please remember that the new @t{dot-config} should include a valid
menuconfig}'' (or @i{gconfig} or @i{kconfig} or the old text-mode @t{DOTCONF_URL} setting, or you won't be able to update the configuration
@i{config}) from the top-level directory of @i{wr-switch-sw}. To at the next boot. In any case, you can always copy a configuration
silently enact the default configuration, run ``@t{make defconfig}'' file using @i{ssh}, or use the web interface to change the configuration.
(this is done by the normal build if no configuration is present). 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.
The released firmware image uses the default configuration, but we'll @c ==========================================================================
soon offer the option to change most of these values at boot-time @node Configuration Items that Apply at Build Time
(by downloading configuration from a network server) or run-time. @section Configuration Items that Apply at Build Time
The following configuration options are available The following items in @t{dot-config} are used at build time; changing
them in the installed version has no effect:
@table @code @table @code
...@@ -313,6 +406,31 @@ The following configuration options are available ...@@ -313,6 +406,31 @@ The following configuration options are available
@t{configs/buildroot} directory; an absolute pathname is used @t{configs/buildroot} directory; an absolute pathname is used
unchanged. 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. When the
value is changed by the web interface, proper action is taken.
@table @code
@item CONFIG_DOTCONF_URL
The 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_NTP_SERVER @item CONFIG_NTP_SERVER
The NTP server used to prime White Rabbit time, at system boot. The NTP server used to prime White Rabbit time, at system boot.
...@@ -358,12 +476,6 @@ The following configuration options are available ...@@ -358,12 +476,6 @@ The following configuration options are available
unknown facility names will generate a runtime error on the switch. unknown facility names will generate a runtime error on the switch.
All three strings default to ``@t{daemon.info}''. All three strings default to ``@t{daemon.info}''.
@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 @end table
@c ############################################################################ @c ############################################################################
......
userspace/rootfs_override/etc/init.d/S20dot-config
View file @ 9a376bca
...@@ -6,8 +6,11 @@ ...@@ -6,8 +6,11 @@
# without the need to rember wheter this is S20 or S10 during boot. # without the need to rember wheter this is S20 or S10 during boot.
# First, read dot-config to get the new location, if any. # First, read dot-config to get the new location, if any.
if [ -f /wr/etc/dot-config ]; then dotconfig=/wr/etc/dot-config
. /wr/etc/dot-config tmpconfig=/tmp/dot-config
if [ -f $dotconfig ]; then
. $dotconfig
fi fi
# Create /etc/resolv.conf, so we can use it. /etc is ramdisk anyways # Create /etc/resolv.conf, so we can use it. /etc is ramdisk anyways
...@@ -30,22 +33,22 @@ if [ -n "$CONFIG_DOTCONF_URL" ]; then ...@@ -30,22 +33,22 @@ if [ -n "$CONFIG_DOTCONF_URL" ]; then
host=$(echo $URL | cut -d/ -f 3) host=$(echo $URL | cut -d/ -f 3)
filename=$(echo $URL | cut -d/ -f 4-) filename=$(echo $URL | cut -d/ -f 4-)
rm -f /tmp/dot-config rm -f $tmpconfig
case $proto in case $proto in
http|ftp) http|ftp)
wget $URL -O /tmp/dot-config wget $URL -O $tmpconfig
;; ;;
tftp) tftp)
tftp -g -r "$filename" -l /tmp/dot-config $host tftp -g -r "$filename" -l $tmpconfig $host
;; ;;
*) *)
echo "Invalid URL for dot-config: \"$URL\"" >& 2 echo "Invalid URL for dot-config: \"$URL\"" >& 2
;; ;;
esac esac
# If it exists and it is not empty or awfully small, trust it # If it exists and it is not empty or awfully small, trust it
if [ -f /tmp/dot-config ] && if [ -f $tmpconfig ] &&
[ $(cat /tmp/dot-config | wc -c) -gt 200 ]; then [ $(cat $tmpconfig | wc -c) -gt 200 ]; then
mv /tmp/dot-config /wr/etc cmp -s $tmpconfig $dotconfig || cp $tmpconfig $dotconfig
fi fi
fi fi
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment