radiusvlan.in

\input texinfo    @c -*-texinfo-*-
%
% radiusvlan.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 radiusvlan.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 radiusvlan.info
@settitle radiusvlan
@iftex
@afourpaper
@end iftex
@paragraphindent none
@comment %**end of header

@setchapternewpage off

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

@finalout

@titlepage
@title White Rabbit Switch: Radius Vlan
@subtitle Description of the Radius Vlan mechanism used in WR switch
@subtitle @value{update-month} (@value{release})
@author A. Rubini
@end titlepage
@headings single

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

@c ##########################################################################
@c Top node is not included in tex
@unnumbered Introduction

This document describes a new feature of the White Rabbit Switch, added
for application at GSI, which is a subset of IEEE 802.1X.

When a devices is detected on a port which is
configured as ``access'', a Radius server is queried for authorization.

The features is called @i{radiusvlan} or @i{rvlan} when a shorter name
is to be preferred.  It relies on @i{radclient}, which was added
to @i{buildroot} in a new @i{freeradius-utils} package. The package
installs @i{radtest}, @i{radclient} and a minimal dictionary (the full
dictionary is more than 1MB worth of data).

It was chosen to install an older version of radclient because the current
version requires a special allocator (libtalloc), that had to be added
to buildroot too.

@c ##########################################################################
@node Related Kconfig Items
@chapter Related Kconfig Items

Like most features in White Rabbit Switch, @i{radiusvlan} is configured
through @i{Kconfig}. The @i{dot-config} file is used both at build time
and at run time (where it lives in @i{/wr/etc}).

This is the list of configuration items related to @i{radiusvlan}. None
of them has effects on the firmware build, they are only used at runtime.

@table @code
@item RVLAN_ENABLE

	The boolean option selects whether the tool is to be run or not.
        If disabled, the tool will not run and the related @i{monit} rule
        won't be activated.  No further config option has any effect if
        this flag is false.

@item RVLAN_PMASK

	A port mask. If any bit in the mask is 0, the associated port will
        not be monitored by the tool. Port @i{wri1} is associated to bit 0,
        and so on until @i{wri18} associated to bit 17.  Bits 18-31 are
        ignored. The default value is all-1.

@item RVLAN_AUTH_VLAN

	A temporary @sc{vid} to be used during port authorization.
        Defaults to 4094.

@item RVLAN_NOAUTH_VLAN

	The @sc{vid} to be used for ports that are not authorized.
        Defaults to 4094.

@item RVLAN_OBEY_DOTCONFIG

	A boolean option. If set, @i{radiusvlan} will obey the @sc{vid}
        value set forth in @i{dot-config} rather than what the Radius
        server returned. Thus, the Radius server's reply is only used
        to authorize or not the port (if not, @t{NOAUTH_VLAN} is applied).

@item RVLAN_RADIUS_SERVERS

	A comma-separated list of the names or IP addresses of a set
        of Radius servers. See @ref{Multiple Servers}.

@item CONFIG_RVLAN_RADIUS_SECRET

	The string used to encrypt radius frames, called ``secret''
        in radius documentation.

@end table


@c ##########################################################################
@node Service Activation and Monitoring
@chapter Service Activation and Monitoring

The tool is a standalone program that ignores its own command line;
all configuration information comes from dot-config, as described
above.

The service is executed at boot from @i{/etc/init.d/radiusvlan}, which
has the same structure of all other similar scripts.

In @i{/etc/rcS}, the symbolic link must be after @i{vlan} configuration.

The service, like most other @i{wrs} services, is monitored by @i{monit},
with the same parameters as all other services.  Working @i{monit} setup
can be confirmed by running

@example
   while true; do killall radiusvlan; sleep 3; done; done
@end example

which will properly trigger a @i{monit-triggered} reboot.

Both invocation and monitoring depend on @i{dot-config}: if @t{RVLAN_ENABLE}
is false, neither of them is activated.

@c ##########################################################################
@node Internal Design
@chapter Internal Design

The tools enumerates all @i{wri*} interfaces in @i{/sys/net/class}.
It opens a @i{netlink} socket to get notification of any change in
interface up/down status, and then checks whether each of them
is up or down (thus, no change can get undetected).

Only ports configured as @t{VLAN_PORTxx_MODE_ACCESS} are monitored,
and only if the corresponding bit in @t{RVLAN_PMASK} is set.

For each monitored port, the tool runs a state machine, where the initial state
is @i{DOWN} or @i{JUSTUP}.  Whenever a state change is reported by
@i{netlink}, the port is moved to either @i{JUSTUP} or @i{GODOWN}.

This is the list of states. No state is blocking, so operation on one
port does not stop operation on other ports (the engine is based
on @i{select()}).

@table @code

@item RVLAN_GODOWN

	This state is the default state for enumerated ports, and it
        is entered whenever @i{netlink} reports that the
        interface went down. This state turns the port to @i{vlan_auth}
        and forgets the peer's mac address.
        It also closes any open file descriptor and
        kills the child process, if it exists.  Thus, no remaining
        garbage remains in the system even if the fiber is unplugged
        and re-plugged quickly several times.

@item RVLAN_DOWN

	The port is quietly down.

@item RVLAN_JUSTUP

	The port was just reported as ``up'' and we must start
        authentication. The first step is identifying the MAC address
        of the peer. Thus, the tool starts sniffing the port, by opening
        a raw socket listening to this port.

@item RVLAN_SNIFF

	Get a frame from the port. If the frame is sent from the switch
        itlsef, it is ignored.  Any address configured in the switch is
        considered as @i{self} (i.e., also the @i{eth0} mac address, used
        by @i{ppsi} as sender address, is ignored).   When a foreign
        frame is received, the tool saves the MAC address of the peer,
        it closes the sniffing socket and it moves to the next state.

@item RVLAN_RADCLIENT

	The tool selects a radius server (see @ref{Multiple Servers},
        and runs @i{radclient}, feeding data
        to its @i{stdin} and collecting its @i{stdout+stderr}. The @i{pid}
        of the child process is retained for later cleanup.

@item RVLAN_AUTH

	@i{radclient} returned some data. This state collects it until EOF.
        If @i{radclient} reports an error in communication, the server
        is marked as ``recently faulty'' and @i{radiusvlan} moves back
        to @t{RVLAN_RACLIENT}, where a different server will be selected.
        If the server replied, the tool looks for ``@t{Framed-User}''
        and ``@t{Tunnel-Private-Group-Id}''. If both exist authentication
        succeeded. The @i{chosen_vlan} is either the one returned by the
        Radius Server or the one set forth in dot-config, according to
        the @t{OBEY_DOTCONFIG} parameter.

@item RVLAN_CONFIG

	This state calls ``@t{wrs_vlans --port <port> --pvid <pvid>''}'',
        where @i{pvid} is @i{noauth_vlan} if authorization failed.
        We then move to @t{CONFIGURED} state.  The external @i{wrs_vlans}
        tool is lazily executed with @i{system(3)}, and thus this state
        is blocking. However, @i{wrs_vlans} completes in no time, so this
        is acceptable in my opinion.

@item RVLAN_CONFIGURED

	The port is quietly running, no action is performed.

@item RVLAN_WAIT

	Wait for the child process to terminate (if we killed it
        in @t{GODOWN}). This is a transient state that leads to @t{DOWN}.

@end table

@c ##########################################################################
@node Multiple Servers
@chapter Multiple Servers

To support multiple Radius servers, @i{radiusvlan} creates an internal
list of possible servers (by splitting the comma-separated list it gets from
dot-config).

When a port needs to call @i{radclient}, it asks for the ``best'' server.
At the beginning, this is the first server listed in the dot-config line.

Then, Whenever @i{radclient} returns, if it exited in error @b{and}
the reply begins with ``@t{radclient:}'', then this is considered a
communication error (which is different from an authorization denial).
Please note that @i{radiusvlan} merges @i{stdout} and @i{stderr} to
the same file descriptor, due to developer laziness.

Communication errors can happen because the server name cannot
be resolved by @sc{dns}; because the shared secret is wrong, or because
the radius server is not running at the selected address.

When such an error happens, the server name is marked as ``recently
faulty'', and another (or the same) server is selected, to resend the
same query. The selection process returns the radius server whose
failure is oldest, among the list of known servers; this ensures that
if two servers are out of order at different times, @i{radiusvlan} sticks
to the one that is currently working, but can get back to the other server
when needed.

Thus, in a dynamic environment where ports feature ``link up'' and
``link down'' over time, we always query the right server, if any
in the list is off-service.  However, when several port go up
at the same time (e.g. at power on time), we may query the wrong server
for all ports, because no failure is yet known to the system when we
see the ``link up'' events.

What follows is an example, in verbose mode, using the string
@t{tornado,gsi.de,192.168.16.201,192.168.16.200} as
@t{CONFIG_RVLAN_RADIUS_SERVERS}.  Here, ``@t{tornado}'' is a host name
but it can't be resolved by @sc{dns} (fast error reporting);
``@t{gsi.de}'' is not responding (slow error); host 201 does not
respond either (slow error); host 200 replies with an authorization error
-- i.e. it does ``@i{exit 1}'', but for a different reason.
The log is augmented with timestamps (minutes:seconds), so we see
that the timeout of @i{radtest} is 16 seconds.

@smallexample
   13:49: Pmask = 0xffffffff
   13:49: Radius server: "tornado"
   13:49: Radius server: "gsi.de"
   13:49: Radius server: "192.168.16.201"
   13:49: Radius server: "192.168.16.200"
   13:49: Interface "wri1": not access mode
   13:49: Check wri2: down
   [...]
   13:50: FSM: wri3: justup -> sniff
   13:51: recvfrom(wri3): 0800-90e2ba456c6b
   13:51: dev wri3 queries server tornado
   13:51: FSM: wri3: sniff -> auth
   13:52: dev wri3, got 63 bytes so far
   13:52: wri3: reaped radclient: 0x00000100
   13:52: wri3: server failed
   13:52: FSM: wri3: auth -> radclient
   13:52: dev wri3 queries server gsi.de
   13:52: FSM: wri3: radclient -> auth
   14:08: dev wri3, got 55 bytes so far
   14:08: wri3: reaped radclient: 0x00000100
   14:08: wri3: server failed
   14:08: FSM: wri3: auth -> radclient
   14:09: dev wri3 queries server 192.168.16.201
   14:09: FSM: wri3: radclient -> auth
   14:25: dev wri3, got 55 bytes so far
   14:25: wri3: reaped radclient: 0x00000100
   14:25: wri3: server failed
   14:25: FSM: wri3: auth -> radclient
   14:25: dev wri3 queries server 192.168.16.200
   14:25: FSM: wri3: radclient -> auth
   14:27: dev wri3, got 46 bytes so far
   14:27: wri3: reaped radclient: 0x00000100
   14:27: dev wri3: vlan 4094
   14:27: FSM: wri3: auth -> config
   14:28: FSM: wri3: config -> configured
@end smallexample

After the above events, if we plug @i{wri2}, only the right server is
queried:

@smallexample
   14:34: FSM: wri2: down -> sniff
   14:34: recvfrom(wri2): 0026-0008546f9863
   14:34: dev wri2 queries server 192.168.16.200
   14:34: FSM: wri2: sniff -> auth
   14:36: dev wri2, got 46 bytes so far
   14:36: wri2: reaped radclient: 0x00000100
   14:36: dev wri2: vlan 4094
   14:36: FSM: wri2: auth -> config
   14:36: FSM: wri2: config -> configured
@end smallexample

@c ##########################################################################
@node Robustness
@chapter Robustness

The tool is designed to be robust. All possible errors are reported back to
the caller (and to @i{stderr}) and no blocking operation is performed.
The only exception is the call to @i{wrs_vlans}, which is blocking.

Any errors in the state machine leaves the port in the same state,
so @i{wrs_vlans} is re-run if it fails, and so on.  Failure in
reading replies from @i{radclient} turn the FSM to @i{GODOWN}, so
the procedure is started again -- because the port is up.

If the Radius server is not reachable @i{radclient} will time out,
as shown, so the state machine is not stuck.

The startup script uses @t{CONFIG_WRS_LOG_OTHER} as a destination for
its own output, and it is verified to work with my local @i{rsyslog}
server.

The only weak point is in understanding @i{radclient}'s replies.
A sane tool would @i{exit(1)} or @i{exit(2)} to mean different things,
but @i{radclient} always does @i{exit(1)}, so we are forced to rely
on the output strings, which might change from one version to the next.

@c ##########################################################################
@node Diagnostic Tools
@chapter Diagnostic Tools

@c ==========================================================================
@node Checking the Current Status
@section Checking the Current Status

You can always see the current configuration by running @t{rvlan-status}.
This example is taken on a running switch, where port @i{wri1} is in
trunk mode (and thus not monitored), and only port @i{wri17} is connected to
a slave, which was authorized:

@smallexample
   nwt0075m66# /wr/bin/rvlan-status
   wri2 (70b3d591e346 <-> ): state down, vlan 0, pid 0, fd -1
   wri3 (70b3d591e347 <-> ): state down, vlan 0, pid 0, fd -1
   wri4 (70b3d591e348 <-> ): state down, vlan 0, pid 0, fd -1
   wri5 (70b3d591e349 <-> ): state down, vlan 0, pid 0, fd -1
   wri6 (70b3d591e34a <-> ): state down, vlan 0, pid 0, fd -1
   wri7 (70b3d591e34b <-> ): state down, vlan 0, pid 0, fd -1
   wri8 (70b3d591e34c <-> ): state down, vlan 0, pid 0, fd -1
   wri9 (70b3d591e34d <-> ): state down, vlan 0, pid 0, fd -1
   wri10 (70b3d591e34e <-> ): state down, vlan 0, pid 0, fd -1
   wri11 (70b3d591e34f <-> ): state down, vlan 0, pid 0, fd -1
   wri12 (70b3d591e350 <-> ): state down, vlan 0, pid 0, fd -1
   wri13 (70b3d591e351 <-> ): state down, vlan 0, pid 0, fd -1
   wri14 (70b3d591e352 <-> ): state down, vlan 0, pid 0, fd -1
   wri15 (70b3d591e353 <-> ): state down, vlan 0, pid 0, fd -1
   wri16 (70b3d591e354 <-> ): state down, vlan 0, pid 0, fd -1
   wri17 (70b3d591e355 <-> 00267b0003d4): state configured, vlan 31, pid 0, fd -1
   wri18 (70b3d591e356 <-> ): state down, vlan 0, pid 0, fd -1
@end smallexample

This works by sending @i{SIGUSR1} to the running @i{radiusvlan}, which
creates @i{/tmp/rvlan-status} with the above information.  If
@i{radiusvlan} is not running, @i{rvlan-status} will report
``@t{radiusvlan: no process found}''.

@c ==========================================================================
@node Looking at Authorization Strings
@section Looking at Authorization Strings

Communication with @i{radclient} happens using @i{stdin} and @i{stdout}.
Currently @i{radiusvlan} saves in @i{/tmp} both files, to help tracing
any errors.  The file names are port-specific, so only the last iteration
will be visible.

There are two example: a successful @i{wri17} authentication and a failed
@i{wri3}authentication:

@smallexample
   nwt0075m66# grep . /tmp/radclient-wri17-*
   /tmp/radclient-wri17-in:User-Name = "00267b0003d4"
   /tmp/radclient-wri17-in:User-Password = "00267b0003d4"
   /tmp/radclient-wri17-out:Received response ID 93, code 2, length = 50
   /tmp/radclient-wri17-out:       Tunnel-Type:0 = 13
   /tmp/radclient-wri17-out:       Tunnel-Medium-Type:0 = IEEE-802
   /tmp/radclient-wri17-out:       Framed-Protocol = PPP
   /tmp/radclient-wri17-out:       Service-Type = Framed-User
   /tmp/radclient-wri17-out:       Tunnel-Private-Group-Id:0 = "2984"

   wrs# grep . /tmp/radclient-wri17-*
   /tmp/radclient-wri3-in:User-Name = "90e2ba456c6b"
   /tmp/radclient-wri3-in:User-Password = "90e2ba456c6b"
   /tmp/radclient-wri3-out:radclient: no response from server for ID 98 socket 4
@end smallexample

@c ==========================================================================
@node Verbose Operation
@section Verbose Operation

If you set @t{RVLAN_VERBOSE} to a non-empty value in the
tool's environment, initial enumeration and state machine changes are
reported to @i{stdout}.

This ``verbose'' mode can also be entered (or left) by seding @t{SIGUSR2},
see below.  This is an example on a running switch where
@i{radiusvlan} was already automatically run:

@smallexample
   wrs# export RVLAN_VERBOSE=y; killall radiusvlan; /wr/bin/radiusvlan
   device wri3 left promiscuous mode
   Pmask = 0xffffffff
   Interface "wri1": not access mode
   Check wri2: up
   Check wri5: down
   Check wri6: down
   Check wri7: down
   Check wri3: up
   Check wri4: down
   Check wri8: down
   [...]
   FSM: device wri3 entered promiscuous mode
   wri2: justup -> sniff
   FSM: wri3: justup -> sniff
   vfrom(wri2): 0026-0008546f9863
   FSM: wri2: sniff -> auth
   recvfrom(wri3): 0800-90e2ba456c6b
   FSM: wri3: sniff -> auth
   dev wri2, got 55 bytes so far
   wri2: reaped radclient: 0x00000100
   dev wri2: vlan 4094
   FSM: wri2: auth -> config
   FSM: wri2: config -> configured
   dev wri3, got 54 bytes so far
   wri3: reaped radclient: 0x00000100
   dev wri3: vlan 4094
   FSM: wri3: auth -> config
   FSM: wri3: config -> configured
@end smallexample

In the above example, two interface were up and authorization failed for
both (as seen, @i{radclient} did @t{exit(1)}).  Both interfaces
are configured in vlan 4094.

@c ==========================================================================
@node Dry-run Operation
@section Dry-run Operation

If @t{RVLAN_DRYRUN} is set to a non-empty value in the
tool's environment, no changes to the vlan configuration will be done.

@c ==========================================================================
@node Forcing Re-Authorizazion
@section Forcing Re-Authorizazion

By sending @i{SIGUSR2} to a running @i{radiusvlan} all state machines
are turned to @t{JUSTUP} so all authorization is retried, and verbose
mode is toggled.  Please note
that this is pretty raw, and should only be run in a quiet system
where all interfaces are @i{configured} or @i{down} (the cleanup of
state @t{GODOWN} is not performed).

The simple script @t{rvlan-debug} can be used to send @t{SIGUR2}
and check the new value of verbosity. This example is in a system
where @i{radiusvlan} was automatically started at boot:

@smallexample
   wrs#rvlan-debug
   radiusvlan verbose level is now 1
@end smallexample

Diagnostic messages are then sent to syslog, using my
@t{CONFIG_WRS_LOG_OTHER} and related configuration choices.
To turn off verbosity, run the command again:

@smallexample
   wrs#rvlan-debug
   radiusvlan verbose level is now 0
@end smallexample

Let me repeat this trivial diagnostic feature is not meant for
production use because it may leave some garbage in the system (e.g. a
zombie @i{radclient} process).

@c ##########################################################################
@node Bugs and Missing Features
@chapter Bugs and Missing Features

A few, unfortunately

@itemize @bullet

@item It is not expected that MAC addresses change. Both identification
of self frames and blessing of peers (for authorization) has an
ever-lasting effect. Clearly, if you change client in a port, the
link-down and link-up events will force authentication on the new mac
address, but if you change the mac address of a PTP slave while
it runs, authorization is not re-run.

@item Vlan configuration only happens with @t{--pvid} configuration,
and no action is performed on the routing table.

@end itemize

The last item is tricky. The White Rabbit Switch must be informed
about vlan-sets, in order to correctly route frames, but those sets
sometimes cannot just be derived by the individual @i{vid} settings.

I was told that for the current application (an ``obey-dotconfig''
one) I should not touch the routing table, but I'm sure this is not
correct for a real multi-vlan setup (especially a dynamic
radius-driven environment).  This should be investigated when new use
cases get real.

@bye