Addressing the “|” separator problem for virtual FTP Sites (FTP 7.5).

FTP 7.0 introduced support for virtual host names as documented in the article Because of variety of compatibility challenges, the decision was made to use the pipe sign “|” as a separator between the virtual host name and the actual account name. To connect to an ftp site configured with virtual host name such as, that was sharing port 21 with some other site, one would need to type|ftpuser to log on successfully.

Pipe sign was intended to address compatibility challenges, but while addressing some, it created new ones as well. One victim of the “I” separator is “Microsoft Expression Web 2” which has a built-in support for FTP publishing. The “|” separator confuses it's credential manager, since it considers it an invalid character which then in turn makes it impossible to connect to virtual FTP site.

To address the issue of “Microsoft Expression Web 2” and possibly other clients that treat “|” in a special way, the updated version of FTP, the FTP 7.5 now allows the administrator to select a new mode of dealing with ftp host names included in the user name.

There is a new configuration setting called useDomainNameAsHostName. What does it do? Just as name suggests, it changes the way how FTP server interprets domain names specified in user name. Microsoft FTP servers has always supported fully qualified user names in the form of

  • DomainName\user
  • ComputerName\user
  • user@DomainName

Often times, it is not required or is not necessary for user to specify the domain name.  If that is the case, then why not to use the familiar syntax to communicate the hostname of the ftp site as if it was a domain name (though it would not be used for the actual windows logon)? That is exactly what FTP 7.5 allows administrator to configure.

If you configure your FTP 7.5 server to allow useDomainNameAsHostName, then it is possible for user to type the virtual host name in the following form


It looks more elegant than the original approach with "|" character, doesn’t it? And it also should be easier to use by many ("|" character should really be reserved for use only by geeks). Not to mention that this will make "Microsoft Expression Web 2" and likely handful of other clients work better.


  1. When useDomainNameAsHostName is set to true, it is still possible to use “I” separator.
  2. If machine’s default domain of the machine is not the one to be used for logon by an ftp site, it is possible to configure defaultLogonDomain in the authentication settings (such as basicAuthentication)
  3. If the FTP user name is to be embedded in the URL (as per RFC1738)  then the  "\" and "@" signs have to be url escaped with %5C for the “\” and %40 for the “@”.
    In the examples to follow I used color coding to differentiate between the hostname that is part of the user name and the hostname used to specify actul. Brown color highlights the user name stored in the URL.
    • can be added to URL as   ftp://
    • can be added to the URL as


Explainer: It surely looks confusing to mention the name of the virtual hostname twice, but it is an unfortunate artifact caused by the lack of first class hostname support by protocol. In the case of HTTP protocol the actual site name from the URL gets communicated to the server so the server then knows what actual name was that client attempting to connect to. In the case of FTP, client software would use the site name in the URL merely for the DNS lookup to find out the IP address of the server to connect to. It will never communicate that name to server. Hence the name has to be entered second time in the username field which then will be sent for server.

Internet Explorer, Windows Explorer and Virtual FTP Sites  issue

Both the Internet Explorer and Windows Explorer first try to connect to FTP server anonymously. If they fail, then they prompt for credentials.When FTP 7 is only configured with virtual host name based sites, these clients fail. Anonymous logon will be be rejected by server the way, that is valid as far as FTP specification (RFC 959) goes, nonetheless, it confuses the authentication sequence of those clients.  Robert McMurray, noticed the problem long time ago and proposed a simple workaround in the following blog

To address the problem, you would need to create a GlobalListenerFtpSite, that is not configured with a host name. It has to deny anonymous access. As a matter of fact you should not allow any access to the site (leave the authorization section empty). This site will reject the anonymous logon the way that is friendly to IE and Windows Explore. Everything will then work as expected. Robert's blog entry will provide more information on the topic.

Configuring the useDomainNameAsHostName using appcmd.exe

To enable the funtionality for all FTP sites running on the server, type in the following on the command line:

%windir%\system32\inetsrv\appcmd.exe set config -section:system.ftpServer/serverRuntime /hostNameSupport.useDomainNameAsHostName:"True" /commit:apphost

Configuring the useDomainNameAsHostName directly editing the applicationhost.config

Add the following snippet to the applicationhost.config file (IIS7 configuration file) to enable the functionality.

        <hostNameSupport useDomainNameAsHostName=”true”/>

1 Comment

  • Dude,
    this is a great article, which really saved my a**... imagine, in my company the standard html editing tool is Sharepoint Designer.
    Anyway, you may want to specify that a restart of the server is needed to get the whole thing working (I tried IISRESET but it wasn't enough).


Comments have been disabled for this content.