regenerate and fix links

Author: alandekok

doc/antora/modules/reference/pages/raddb/dictionary.adoc

@@ -11,9 +11,9 @@ edited by local administrators.  It will be loaded
 
 NOTE: We recommend using local variables inside of "unlang"
       sections instead of defining attributes in this file. See
-      the xref:reference:index.adoc[reference documentation]
+      the xref:index.adoc[reference documentation]
       for more information on
-      xref:reference:unlang/local.adoc[local variables].
+      xref:unlang/local.adoc[local variables].
 
 
 This file exists for two purposes:
@@ -81,37 +81,43 @@ required, or add your own.
 
 
 
-## v3 Compatible names.
+## v3 Compatibility and Migration
 
-All of the attributes have been renamed from v3.  This change was
-necessary in order to support new functionality in v4.  The
-unfortunate side effect of this change is that all of the names in
-SQL, LDAP, and the "files" module are incompatible with v4.
+By default, the server does NOT load the v3 names.  While this
+behavior is done to simplify the server configuration, it can also
+make migration more difficult.
 
-We recognize that is is difficult to change every entry in a
-database, especially when there's no clear mapping between the
-"old" and "new" names.  This renaming is made more complex because
-the "new" names need to be grouped and arranged in ways that the
-old ones were not.
+If your system is using Vendor-Specific attributes from a
+particular vendor, you can list those dictionaries below.  The
+server will then load the version 3 names, which makes migration
+much simpler.
 
-The "old" names were all in flat lists, so that User-Name appeared
-next to Cisco-AVPAir.  This organization was simple enough to work
-for 20 years, but its time has come.  The new names are
-hierarchical, so that the organization is nested by definition.
+For v4, all of the attributes have been renamed from v3.  This
+change was necessary in order to support new functionality.  The
+unfortunate side effect of this change is that all of the names
+used by v3 in tje SQL, LDAP, and "files" module are incompatible
+with v4.
 
-For v4, the Cisco-AVPair attribute is called "AVPair", and it lives
-inside of the "Cisco" namespace, which in turn lives inside of the
-"Vendor-Specific" namespace.  So the new name for Cisco-AVPair is
-Vendor-Specific.Cisco.AVPair.
+The problem with v3 was that names were all in flat lists, so that
+User-Name appeared in the same to Cisco-AVPAir.  This organization
+was simple enough to work for 25 years, but its time has come.  The
+new names are hierarchical, which means they are organized into a
+tree-like structure.
 
-This process continues for many thousands of vendor-specific
-attributes.
+For v4, the Cisco-AVPair attribute is now called "AVPair".  It
+lives inside of the "Cisco" namespace, which in turn lives inside
+of the "Vendor-Specific" namespace.  So the new name for
+`Cisco-AVPair` is `Vendor-Specific.Cisco.AVPair`.
 
-Happily, it is possible to (mostly) use the old names with v4.
-There are limitations, but it will mostly work.  The main reason
-for enabling the old names is to try out v4 with a database that is
-also used by v3.  This lets you test that v4 works, without going
-through a complex "upgrade everything" process.
+These changes have been made for many hundreds of dictionary files,
+and many thousands of Vendor-Specific attributes.
+
+In the interest of compatibility, is possible to use the old names
+with v4.  There are limitations, but it will generally work.  The
+main reason for enabling the old names is to try out v4 with a
+database that is also used by v3.  This lets you test that v4
+works, without going through a complex "upgrade everything"
+process.
 
 The old v3 names are in "alias" dictionaries, in the `${dictdir}`
 directory.  To find out where this directory is on your local
@@ -120,14 +126,14 @@ command-line option, and it will tell you where the dictionary
 files are located.
 
 The v3 names are in `${dictdir}/radius/alias/VENDOR.txt` where
-_VENDOR_ is the name of the vendor, which is taken from the `VENDOR`
-definition in the v3 dictionaries.
+_VENDOR_ is the name taken from the v3 `dictionary.VENDOR`.
 
-You will need to add a `$INCLUDE` line for each vendor-specific
-dictionary which is used by your local system.  The default v4
-dictionaries do not enable all of v3 compatibility names.
+You will need to edit the text below to add a `$INCLUDE` line for
+each vendor-specific dictionary which is used by your local system.
+The default v4 dictionaries do not enable all of v3 compatibility
+names.
 
-Yes, we recognize that this process is a bit of work.  However, we
+We recognize that this process is a bit of work.  However, we
 wish to encourage everyone using v4 to upgrade to using the new v4
 features.  Our experience shows that if we automatically enable
 "compatibility functions", then those compatibility functions will
@@ -136,8 +142,13 @@ upgrades and ongoing support.  Easy upgrades will mean complex
 ongoing support.  Complex upgrades make ongoing support easier, but
 also make it less likely that people will upgrade.
 
+Note that if you over-write the "v3/dictionary.VENDOR" files with a
+copy of the v3 dictionary, then it won't work.  Migrations across
+major version numbers means that the configuration files are *not*
+100% compatible. This includes the dictionaries!
 
 All of the v3 compatibility names are in the RADIUS namespace.
+There are no aliases for DHCPv4.
 
 
 
@@ -147,7 +158,8 @@ All of the v3 compatibility names are in the RADIUS namespace.
 #DEFINE	My-Local-String		string
 #DEFINE	My-Local-IPAddr		ipaddr
 #DEFINE	My-Local-Integer	integer
-BEGIN-PROTOCOL RADIUS
-$INCLUDE ${dictdir}/radius/alias/microsoft.txt
-END-PROTOCOL RADIUS
+#BEGIN-PROTOCOL RADIUS
+#$INCLUDE ${dictdir}/radius/v3/dictionary.cisco
+#$INCLUDE ${dictdir}/radius/v3/dictionary.aruba
+#END-PROTOCOL RADIUS
 ```

raddb/dictionary

@@ -16,7 +16,7 @@
 #        sections instead of defining attributes in this file. See
 #        the xref:reference:index.adoc[reference documentation]
 #        for more information on
-#        xref:reference:unlang/local.adoc[local variables].
+#        xref:unlang/local.adoc[local variables].
 #
 #
 #  This file exists for two purposes: