update docs and rename

after some thought (finally), it makes more sense to drop the
"alias/foo.txt" names, and instead use "v3/dictionary.foo".

It is now clearer that the names are for v3 compatibility.

Author: alandekok

raddb/dictionary

@@ -87,37 +87,43 @@
 #DEFINE	My-Local-Integer	integer
 
 #
-#  ## v3 Compatible names.
-#
-#  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.
-#
-#  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.
-#
-#  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, 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.
-#
-#  This process continues for many thousands of vendor-specific
-#  attributes.
-#
-#  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.
+#  ## v3 Compatibility and Migration
+#
+#  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.
+#
+#  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.
+#
+#  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.
+#
+#  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.
+#
+#  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`.
+#
+#  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
@@ -126,14 +132,14 @@
 #  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
@@ -142,10 +148,16 @@
 #  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.
 #
 
 #BEGIN-PROTOCOL RADIUS
-#$INCLUDE ${dictdir}/radius/alias/cisco.txt
+#$INCLUDE ${dictdir}/radius/v3/dictionary.cisco
+#$INCLUDE ${dictdir}/radius/v3/dictionary.aruba
 #END-PROTOCOL RADIUS

raddb/radiusd.conf.in

@@ -648,6 +648,8 @@ global {
 #  Some of these flags can also be passed on the command line as
 #  `-S flag=value`.
 #
+#  Dictionary migration instructions can be found in `${raddbdir}/dictionary`.
+#
 migrate {
 	#
 	#  rewrite_update:: Rewrite old `update` sections to use the new