FTP Provider Activation <activation>

Overview

The <activation> element of the <providerDefinitions> element defines a collection of custom name/value pairs that specify any parameters that a custom provider requires.

Note: This element was added in FTP 7.5.

Beginning with FTP 7.5, the FTP service supports extensibility for custom authentication and roles, logging, and home directory lookups. When you create an extensibility provider, you must first register it in the .NET Global Assembly Cache (GAC) for managed-code providers, or in your system's registry for native-code (COM) providers. For additional information about how to create FTP custom providers, see the following section on Microsoft's IIS.net Web site:

Developing for FTP 7.5

Compatibility

Version Notes
IIS 7.5 The <activation> element of the <providerDefinitions> element ships as a feature of FTP 7.5.
IIS 7.0 The <activation> element was not part of FTP 7.0.
IIS 6.0 The FTP service in IIS 6.0 did not support extensibility.

Note: The FTP 7.0 and FTP 7.5 services shipped out-of-band for IIS 7.0, which required downloading and installing the modules from the following URL:

http://www.iis.net/expand/FTP

With Windows 7 and Windows Server 2008 R2, the FTP 7.5 service ships as a feature for IIS 7.5, so downloading the FTP service is no longer necessary.

Setup

To support FTP publishing for your Web server, you must install the FTP service. To do so, use the following steps.

IIS 7.5 for Windows Server 2008 R2

  1. On the taskbar, click Start, point to Administrative Tools, and then click Server Manager.
  2. In the Server Manager hierarchy pane, expand Roles, and then click Web Server (IIS).
  3. In the Web Server (IIS) pane, scroll to the Role Services section, and then click Add Role Services.
  4. On the Select Role Services page of the Add Role Services Wizard, expand FTP Server.
  5. Select FTP Service.

    Note: To support ASP.Membership authentication or IIS Manager authentication for the FTP service, you will also need to select FTP Extensibility.
  6. Click Next.
  7. On the Confirm Installation Selections page, click Install.
  8. On the Results page, click Close.

IIS 7.5 for Windows 7

  1. On the taskbar, click Start, and then click Control Panel.
  2. In Control Panel, click Programs and Features, and then click Turn Windows Features on or off.
  3. Expand Internet Information Services, and then FTP Server.
  4. Select FTP Service.

    Note: To support ASP.Membership authentication or IIS Manager authentication for the FTP service, you will also need to select FTP Extensibility.
  5. Click OK.

IIS 7.0 for Windows Server 2008 and Windows Vista

  1. Download the installation package from the following URL:
  2. Follow the instructions in the following walkthrough to install the FTP service:

How To

How to add a managed-code custom authentication provider for an FTP site

Note: These steps assume that a custom FTP authentication provider has already been installed and registered on your server's Global Assembly Cache (GAC.) For more information about how to register managed assemblies, see the Global Assembly Cache Tool (Gacutil.exe) topic on Microsoft the MSDN Web site.

  1. Determine the assembly information for the extensibility provider:
    • In Windows Explorer, open your "C:\Windows\assembly" path, where C: is your operating system drive.
    • Locate the assembly. For example, FtpAuthenticationDemo.
    • Right-click the assembly, and then click Properties.
    • Copy the Culture value. For example, Neutral.
    • Copy the Version number. For example, 1.0.0.0.
    • Copy the Public Key Token value. For example, 426f62526f636b73.
    • Click Cancel.
  2. Add the extensibility provider to the global list of FTP authentication providers:
    • Open Internet Information Services (IIS) Manager.
    • Click your computer name in the Connections pane.
    • Double-click FTP Authentication in the main window.
    • Click Custom Providers... in the Actions pane.
    • Click Register.
    • Enter a friendly name for the custom authentication provider in the Name box. For example, FtpAuthenticationDemo.
    • Click Managed Provider (.NET).
    • Enter the assembly information for the extensibility provider using the information that you copied earlier. For example:
      FtpAuthentication.FtpAuthDemo, FtpAuthenticationDemo, version=1.0.0.0, Culture=neutral, PublicKeyToken=426f62526f636b73
    • Click OK.
    • Clear the check box for the custom authentication provider in the providers list.
    • Click OK.
  3. Add the custom authentication provider for an FTP site:
    • Open an FTP site in Internet Information Services (IIS) Manager.
    • Double-click FTP Authentication in the main window.
    • Click Custom Providers... in the Actions pane.
    • Check to select and enable the custom authentication provider in the providers list.
    • Click OK.

Configuration

The <activation> element of the <providerDefinitions> element is configured at the global level in ApplicationHost.config.

Attributes

None.

Child Elements

Element Description
providerData Optional element.

Specifies the collection of key/value pairs that contain the data for a custom provider.

Configuration Sample

The following sample illustrates several configuration settings in the global <system.ftpServer> element for a server. More specifically, the settings in this example demonstrate how to:

  • Enable FTP credential caching and specify a time-out of 10 minutes (600 seconds.)
  • Configure the low port as 5000 and the high port as 6000 for data channel communications.
  • Enable logging and specify that log files will be kept per-site, and that log files will be rotated daily by UTC time.
  • Specify a custom FTP provider and specify a custom parameter for that provider.
  • Specify global IP restrictions that allow FTP access from local host and deny access to the 169.254.0.0 to 169.254.255.255 block of IP addresses.
  • Configure request filtering with the following options:
    • Block FTP access to the _vti_bin virtual directory, which is used with the FrontPage Server Extensions.
    • Block several file types that are associated with executables.
    • Specify 100MB as the maximum file size.
  • Add a global authorization rule that allows access for the administrators group.
  • Specify that domain name syntax can be used for FTP virtual host names.
<system.ftpServer>
   <caching>
      <credentialsCache enabled="true" flushInterval="600" />
   </caching>
   <firewallSupport lowDataChannelPort="5000" highDataChannelPort="6000" />
   <log centralLogFileMode="Site">
      <centralLogFile period="Daily" localTimeRollover="false" enabled="true" />
   </log>
   <providerDefinitions>
      <add name="FtpXmlAuthentication"
         type="FtpXmlAuthentication, FtpXmlAuthentication, version=1.0.0.0, Culture=neutral, PublicKeyToken=426f62526f636b73" />
      <activation>
         <providerData name="FtpXmlAuthentication">
            <add key="xmlFileName" value="C:\Inetpub\XmlSample\Users.xml" />
         </providerData>
      </activation>
   </providerDefinitions>
   <security>
      <ipSecurity enableReverseDns="false" allowUnlisted="true">
         <add ipAddress="169.254.0.0" subnetMask="255.255.0.0" allowed="false" />
         <add ipAddress="127.0.0.1" allowed="true" />
      </ipSecurity>
      <requestFiltering>
         <hiddenSegments>
            <add segment="_vti_bin" />
         </hiddenSegments>
         <fileExtensions allowUnlisted="true">
            <add fileExtension="exe" allowed="false" />
            <add fileExtension="cmd" allowed="false" />
            <add fileExtension="com" allowed="false" />
            <add fileExtension="bat" allowed="false" />
         </fileExtensions>
         <requestLimits maxAllowedContentLength="104857600" />
      </requestFiltering>
      <authorization>
         <add accessType="Allow" roles="administrators" permissions="Read, Write" />
      </authorization>
   </security>
   <serverRuntime>
      <hostNameSupport useDomainNameAsHostName="true" />
   </serverRuntime>
</system.ftpServer>

Sample Code

The following examples add a custom FTP provider definition to a server, and then add a data parameter for that provider.

AppCmd.exe

appcmd.exe set config -section:system.ftpServer/providerDefinitions /+"[name='FtpXmlAuthentication',type='FtpXmlAuthentication, FtpXmlAuthentication, version=1.0.0.0, Culture=neutral, PublicKeyToken=426f62526f636b73']" /commit:apphost

appcmd.exe set config -section:system.ftpServer/providerDefinitions /+"activation.[name='FtpXmlAuthentication']" /commit:apphost

appcmd.exe set config -section:system.ftpServer/providerDefinitions /+"activation.[name='FtpXmlAuthentication'].[key='xmlFileName',value='C:\Inetpub\wwwroot\App_Data\Users.xml']" /commit:apphost

Note: You must be sure to set the commit parameter to apphost when you use AppCmd.exe to configure these settings. This commits the configuration settings to the appropriate location section in the ApplicationHost.config file.

C#

using System;
using System.Text;
using Microsoft.Web.Administration;

internal static class Sample
{
   private static void Main()
   {
      using (ServerManager serverManager = new ServerManager())
      {
         Configuration config = serverManager.GetApplicationHostConfiguration();
         ConfigurationSection providerDefinitionsSection = config.GetSection("system.ftpServer/providerDefinitions");
         ConfigurationElementCollection providerDefinitionsCollection = providerDefinitionsSection.GetCollection();

         ConfigurationElement addElement = providerDefinitionsCollection.CreateElement("add");
         addElement["name"] = @"FtpXmlAuthentication";
         addElement["type"] = @"FtpXmlAuthentication, FtpXmlAuthentication, version=1.0.0.0, Culture=neutral, PublicKeyToken=426f62526f636b73";
         providerDefinitionsCollection.Add(addElement);

         ConfigurationElementCollection activationCollection = providerDefinitionsSection.GetCollection("activation");
         ConfigurationElement providerDataElement = activationCollection.CreateElement("providerData");
         providerDataElement["name"] = @"FtpXmlAuthentication";

         ConfigurationElementCollection providerDataCollection = providerDataElement.GetCollection();
         ConfigurationElement addElement1 = providerDataCollection.CreateElement("add");
         addElement1["key"] = @"xmlFileName";
         addElement1["value"] = @"C:\Inetpub\wwwroot\App_Data\Users.xml";
         providerDataCollection.Add(addElement1);
         activationCollection.Add(providerDataElement);

         serverManager.CommitChanges();
      }
   }
}

VB.NET

Imports System
Imports System.Text
Imports Microsoft.Web.Administration

Module Sample
   Sub Main()
      Dim serverManager As ServerManager = New ServerManager
      Dim config As Configuration = serverManager.GetApplicationHostConfiguration
      Dim providerDefinitionsSection As ConfigurationSection = config.GetSection("system.ftpServer/providerDefinitions")
      Dim providerDefinitionsCollection As ConfigurationElementCollection = providerDefinitionsSection.GetCollection

      Dim addElement As ConfigurationElement = providerDefinitionsCollection.CreateElement("add")
      addElement("name") = "FtpXmlAuthentication"
      addElement("type") = "FtpXmlAuthentication, FtpXmlAuthentication, version=1.0.0.0, Culture=neutral, PublicKeyToken=426f62526f636b73"
      providerDefinitionsCollection.Add(addElement)

      Dim activationCollection As ConfigurationElementCollection = providerDefinitionsSection.GetCollection("activation")
      Dim providerDataElement As ConfigurationElement = activationCollection.CreateElement("providerData")
      providerDataElement("name") = "FtpXmlAuthentication"

      Dim providerDataCollection As ConfigurationElementCollection = providerDataElement.GetCollection
      Dim addElement1 As ConfigurationElement = providerDataCollection.CreateElement("add")
      addElement1("key") = "xmlFileName"
      addElement1("value") = "C:\Inetpub\wwwroot\App_Data\Users.xml"
      providerDataCollection.Add(addElement1)
      activationCollection.Add(providerDataElement)

      serverManager.CommitChanges()
   End Sub
End Module

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST";

var providerDefinitionsSection = adminManager.GetAdminSection("system.ftpServer/providerDefinitions", "MACHINE/WEBROOT/APPHOST");
var providerDefinitionsCollection = providerDefinitionsSection.Collection;

var addElement = providerDefinitionsCollection.CreateNewElement("add");
addElement.Properties.Item("name").Value = "FtpXmlAuthentication";
addElement.Properties.Item("type").Value = "FtpXmlAuthentication, FtpXmlAuthentication, version=1.0.0.0, Culture=neutral, PublicKeyToken=426f62526f636b73";
providerDefinitionsCollection.AddElement(addElement);

var activationCollection = providerDefinitionsSection.ChildElements.Item("activation").Collection;
var providerDataElement = activationCollection.CreateNewElement("providerData");
providerDataElement.Properties.Item("name").Value = "FtpXmlAuthentication";
var providerDataCollection = providerDataElement.Collection;

var addElement1 = providerDataCollection.CreateNewElement("add");
addElement1.Properties.Item("key").Value = "xmlFileName";
addElement1.Properties.Item("value").Value = "C:\\Inetpub\\wwwroot\\App_Data\\Users.xml";
providerDataCollection.AddElement(addElement1);
activationCollection.AddElement(providerDataElement);

adminManager.CommitChanges();

VBScript

Set adminManager = createObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST"

Set providerDefinitionsSection = adminManager.GetAdminSection("system.ftpServer/providerDefinitions", "MACHINE/WEBROOT/APPHOST")
Set providerDefinitionsCollection = providerDefinitionsSection.Collection

Set addElement = providerDefinitionsCollection.CreateNewElement("add")
addElement.Properties.Item("name").Value = "FtpXmlAuthentication"
addElement.Properties.Item("type").Value = "FtpXmlAuthentication, FtpXmlAuthentication, version=1.0.0.0, Culture=neutral, PublicKeyToken=426f62526f636b73"
providerDefinitionsCollection.AddElement(addElement)

Set activationCollection = providerDefinitionsSection.ChildElements.Item("activation").Collection
Set providerDataElement = activationCollection.CreateNewElement("providerData")
providerDataElement.Properties.Item("name").Value = "FtpXmlAuthentication"
Set providerDataCollection = providerDataElement.Collection

Set addElement1 = providerDataCollection.CreateNewElement("add")
addElement1.Properties.Item("key").Value = "xmlFileName"
addElement1.Properties.Item("value").Value = "C:\Inetpub\wwwroot\App_Data\Users.xml"
providerDataCollection.AddElement(addElement1)
activationCollection.AddElement(providerDataElement)

adminManager.CommitChanges()
Deprecated Elements