OpenVPN/FRP

From Secure Computing Wiki
Revision as of 05:24, 26 February 2010 by Mattock (Talk | contribs) (Overview of the FRP process)

Jump to: navigation, search

The FRP process

Overview

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.

Moving features "down the ladder"

Probably the most straightforward way to move features "down the ladder" is when new stable releases are made. Assuming one release takes ~12 months and a feature is deprecated in "testing" just after a stable release is made, it will stay in the code for

  • 12 months (in testing, outputs a runtime warning)
  • 12 months (in stable, outputs a runtime warning)
  • 12 months (in stable + 1, disabled but available)

So it'll take 24 - 36 months to get rid of a feature, depending on when (in the release cycle) it's deprecated. There are ways to speed up the process. We can, for example, have two processes depending on feature type:

  1. Longer process for features we know people depend on, but which need to be removed nevertheless (for whatever reason)
  2. Shorter process for features somebody _might_ use - like the randomization feature discussed earlier

The full FRP (see the wiki link) with steps 1-4 would suit type 1 features. Type 2 features could skip step 3 ("disabled but available") to save time. It should be relatively easy to spot type 1 features: a mail to the -users mailing list should trigger loud complaints if a feature is widely used. Also, users have plenty of time to react to the warnings during the 12-24 month period.

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.
    • 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