Difference between revisions of "OpenVPN/FRP"

From Secure Computing Wiki
Jump to: navigation, search
(Third phase: Complete removal of the feature)
m (The FRP process)
Line 1: Line 1:
= The FRP process =
+
= Overview of the FRP process =
  
 
The initial process was drafted in the [[OpenVPN/IRC_meetings|IRC meeting]] on 18th Feb 2010. It has since been discussed in detail on the  [http://sourceforge.net/mailarchive/forum.php?forum_name=openvpn-devel devel mailinglist] in the ''"[PATCH v2] Do not randomize resolving of IP addresses in getaddr()"'' thread.
 
The initial process was drafted in the [[OpenVPN/IRC_meetings|IRC meeting]] on 18th Feb 2010. It has since been discussed in detail on the  [http://sourceforge.net/mailarchive/forum.php?forum_name=openvpn-devel devel mailinglist] in the ''"[PATCH v2] Do not randomize resolving of IP addresses in getaddr()"'' thread.

Revision as of 06:45, 24 February 2010

Overview of the FRP process

The initial process was drafted in the IRC meeting on 18th Feb 2010. It has since been discussed in detail on the devel mailinglist in the "[PATCH v2] Do not randomize resolving of IP addresses in getaddr()" thread.

  1. Ask users if they are depending on a feature considered for deprecation (e.g. using the openvpn-users mailing list)
    • If users complain, discuss the issue and possible solutions with them
    • If there are no complaints, proceed to 2
  2. Warn the user about feature deprecation on application startup. The deprecated code itself can also output a warning itself, depending on how often it's triggered. The warning can be a simple log message (e.g. "WARNING: this feature is being deprecated and will be removed soon"). The deprecated code will still be enabled by default.
    • If users complain now, discuss the issue and possible solutions with them
    • If there are no complaints, proceed to 3
  3. Make the feature disabled by default, but allow enabling it at compile-time
    • If users complain now, discuss the issue and possible solutions with them
    • If there are no complaints, proceed to 4
  4. Remove the feature entirely from the code
    • If users complain now, discuss the issue and possible solutions with them
    • If there are no complaints, proceed to 5
  5. Finished. The feature was not really important to anyone and is not cluttering the code anymore.

Each feature could be kept around in "deprecated" mode in the first stable release, disabled but available in the second and removed in the third release. This will give users plenty of time to reach, depending on the release cycle.

It is also necessary that each feature deprecation / removal needs is documented visibly in the release notes of each stable release.

What to do - code wise

First phase: Disable the feature on request

  • Remove the feature by using #ifdef's wherever this feature is called or executed in the source code
    • The #ifdef name should start with DEPRECATED_ and then a sensible name for the feature
    • Add a warning (using #warning statements) for compile time warnings when the feature is enabled.
    • Add log messages (using msg()) whenever this feature is called.
      • Make sure that the logging will not be too extensive and happen too often. It should catch attention, but not flood the log.
    • [TBD] Update deprecated.c and add an appropriate warning, inside a #ifdef block for the feature going through the FRP.
  • Update configure.ac
    • Locate the section for deprecated features, (search for "Deprecated features")
    • Add a new configure argument to disable this feature, ie. enabled by default. The argument should start with --disable-depr- and then a sensible and descriptive feature name.
  • Test the change by compiling and smoke testing OpenVPN.
    • When the feature is enabled (the default)
      • A warning should be clearly visible during compilation
      • OpenVPN should provide a warning early at startup about a enabled deprecated feature
      • OpenVPN should create a log entry whenever the feature's code path is hit
      • Verify that the feature indeed still works
    • When the feature is disabled (through ./configure arguments)
      • No warning about the feature deprecation should be seen at startup
      • No warning or errors when OpenVPN passes the code path where this feature was enabled
      • Verify that the feature really is removed when running OpenVPN and that it behaves as expected
  • Commit the patch(es) and submit them to the openvpn-devel mailinglist. The subject must start with [PATCH] followed by FRP:
    • Example: [PATCH] FRP: Preparing for removal of feature X

Second phase: Enable the feature on request

  • Update configure.ac
    • Rename argument from --disable-depr-* to --enable-depr-*
    • Change default value from "yes" to "no"
  • Test the change by compiling and smoke testing OpenVPN.
    • When the feature is disabled (the default)
      • No warning about the feature deprecation should be seen at startup
      • No warning or errors when OpenVPN passes the code path where this feature was enabled
      • Verify that the feature really is removed when running OpenVPN and that it behaves as expected
    • When the feature is enabled (through ./configure arguments)
      • A warning should be clearly visible during compilation
      • OpenVPN should provide a warning early at startup about a enabled deprecated feature
      • OpenVPN should create a log entry whenever the feature's code path is hit
      • Verify that the feature indeed still works
  • Commit the patch(es) and submit them to the openvpn-devel mailinglist. The subject must start with [PATCH] followed by FRP2:
    • Example: [PATCH] FRP2: Deprecating feature X by default

Third phase: Complete removal of the feature

  • Remove all code blocks which are encapsulated by the feature's #ifdef blocks from the source code
    • Beware of #else blocks, and make sure they are not removed.
  • Update configure.ac
    • Remove the configure arguments related to the feature
  • Test the change by compiling and smoke testing OpenVPN. Check that:
    • No warning about the feature deprecation should be seen at startup
    • No warning or errors when OpenVPN passes the code path where this feature was enabled
    • Verify that the feature really is removed when running OpenVPN and that it behaves as expected
  • Commit the patch(es) and submit them to the openvpn-devel mailinglist. The subject must start with [PATCH] followed by FRP3:
    • Example: [PATCH] FRP3: Removing deprecated feature X