/usr/share/doc/proftpd-doc/howto/Vhost.html is in proftpd-doc 1.3.5e-1build1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 | <!-- $Id: Vhost.html,v 1.7 2009-01-12 23:41:26 castaglia Exp $ -->
<!-- $Source: /home/proftpd-core/backup/proftp-cvsroot/proftpd/doc/howto/Vhost.html,v $ -->
<html>
<head>
<title>ProFTPD mini-HOWTO - Virtual Servers</title>
</head>
<body bgcolor=white>
<hr>
<center><h2><b>ProFTPD and Virtual Servers</b></h2></center>
<hr>
<p><a name="Definition"></a>
<b>What is a virtual server?</b><br>
A virtual server, also known as a virtual host (or <i>vhost</i> for short),
refers to the practice of serving more than one address/site on a single host
machine. The fact that these multiple sites are being served by the same
physical machine is transparent to the end user.
<p>
The definition of the File Transfer Protocol, unfortunately, does not
(currently) support name-based virtual hosts, as HTTP1.1 supports. All FTP
virtual hosts are based on unique IP address/port combinations, not on DNS
names. The similarity of ProFTPD's configuration file syntax to Apache's
sometimes leads users to assuming that <code>proftpd</code> will handle these
the same way -- but more on this later. The bottom line is that ProFTPD
does not support name-based virtual hosts; not because they are not implemented,
but simply because the protocol itself does not support them.
<p>
In some documents, one might see reference to both "daemon" and
"server". Sometimes these words are used interchangeably; however,
there is a slight difference. A "daemon" is a long-lived process
on a host machine, and a "server" is a process that provides some
service, typically to remote clients. A process, such as a standalone
<code>proftpd</code> process, can be considered both a "daemon"
and a "server". With this in mind, then, a "virtual server"
is not a separate process itself; it just looks like one to the remote clients.
Hence the "virtual".
<p><a name="Configuration"></a>
There are three "server" contexts (sometimes also called
<i>sections</i>) in the <code>proftpd.conf</code> configuration file:
<a href="http://www.proftpd.org/docs/directives/linked/config_ref_VirtualHost.html"><code><VirtualHost></code></a>, <a href="http://www.proftpd.org/docs/directives/linked/config_ref_Global.html"><code><Global></code></a>, and "server config".
<p>
The <code><VirtualHost></code> context is used to define the configuration
for a particular virtual host, bound to an IP address. For example:
<pre>
<VirtualHost 1.2.3.4>
...
</VirtualHost>
</pre>
defines a configuration for a virtual server that <code>proftpd</code> should
use whenever a remote client connects to the IP address 1.2.3.4. DNS names,
too, can be used with the <code><VirtualHost></code> configuration
directive, and this is where some of the name-based vhost support confusion
creeps in:
<pre>
<VirtualHost ftp.mydomain.com>
...
</VirtualHost>
</pre>
When <code>proftpd</code> parses this context on startup, it will resolve the
given DNS name to its IP address and use that, just as if that IP address
had been used in the first place. Use of DNS names like this, while convenient,
can easily lead to confusion when multiple DNS names resolve to the same
IP address. If this happens, <code>proftpd</code> will use the first
context in the configuration file when serving that address.
<p>
The <code><Global></code> context is provided as a convenience. Imagine
that the administrator has many <code><VirtualHost></code> contexts
in her <code>proftpd.conf</code>, and yet has a lot of the same configuration
for each virtual host, such as common <code><Directory></code> sections,
<code>DefaultRoot</code> settings, <i>etc</i>. Rather than including the
same configuration over and over, she could use the <code><Global></code>
context:
<pre>
<Global>
...
</Global>
</pre>
Anything inside of a <code><Global></code> section is applied to every
server configuration in the file, to every <code><VirtualHost></code> as
well as the default "server config" server.
<p>
Which brings us to the "server config" context. The name is
ill-suited, and is really borrowed directly from Apache's naming conventions.
The "server config" context refers to anything not in a
<code><VirtualHost></code> or <code><Global></code> context in
the <code>proftpd.conf</code> file. Unlike Apache's <code>httpd.conf</code>,
ProFTPD's configuration is designed such that one should be able to use
the simplest file as possible. In fact, <code>proftpd</code> will start
if the <code>proftpd.conf</code> is completely empty; try it! This will
cause the daemon to use all of the default settings, which in most cases
is not what is wanted, but it <i>is</i> possible. With this in mind,
there is always at least one server configuration present: the default server
context, and it is this context that is known as the "server config".
Just like the <code><VirtualHost></code> context, any configuration
directives inside the "server config" context <b>do not apply</b>
outside of the context. Many administrators often assume that this is the
case. It is not. This is what the <code><Global></code> context
is for.
<p>
However, one particular drawback to the "server config" context was
that it did not provide a way to specify to which IP address that configuration
pertained. By default, when <code>proftpd</code> parses the
<code>proftpd.conf</code> file, it will use the <code>gethostname()</code>
function to determine the IP address to which the default server should listen.
On a single address, single interface system, this default is fine. It is one
a multiple address system that the default handling does not always work;
the administrator may wish to explicitly specify to which address the default
server should listen. This is what the <a href="http://www.proftpd.org/docs/directives/linked/config_ref_DefaultAddress.html"><code>DefaultAddress</code></a>
configuration directive provides: the ability to specify to which IP address
the "server config" vhost should listen.
<p>
By default, every server will listen to port 21, the IANA standard port for
FTP. If you want to have server react to a different port, use the
<a href="http://www.proftpd.org/docs/directives/linked/config_ref_Port.html"><code>Port</code></a> directive to change the port. As might be mentioned
elsewhere, if you have many different <code><VirtualHost></code> contexts
using the same address but different ports, you'll want to make sure that
you leave each <code>Port</code>-1 number empty. <a href="http://www.faqs.org/rfcs/rfc959.html">RFC 959</a> specifies that the source port for an active
data transfer (read <a href="http://slacksite.com/other/ftp.html">here</a>)
must be <code>L-1</code>, where <code>L</code> is the port on which your server
listens. Also, as mentioned in the <code>Port</code> documentation, using:
<pre>
Port 0
</pre>
in any server context will effectively "disable" that server. This
is sometimes used to disable the "server config" configuration.
<p>
There is another configuration directive that comes into play in all of this
: <a href="http://www.proftpd.org/docs/directives/linked/config_ref_DefaultServer.html"><code>DefaultServer</code></a>. Here is why: when a client
contacts <code>proftpd</code>, the server has to determine which configuration
to use for handling the client. To do this, it searches its list of configured
vhosts, searching for a vhost whose IP address matches the IP address that the
client contacted. If there's a matching vhost for that IP address, simple:
use that configuration. If not, <code>proftpd</code> will then resort to
using the configuration that bears the <code>DefaultServer</code> directive,
which says that the server configuration in which it appers should be used
in cases like this. If there is no <code>DefaultServer</code> directive
in the <code>proftpd.conf</code> file, and no matching configuration can
be found, then the client will see a message such as "no server available
to service your request". The <code>DefaultServer</code> can be
used to say that a <code><VirtualHost></code> should be the default,
and not necessarily the "server config" context, as is common.
<p>
If you would like the same virtual host configuration to be used for
multiple different IP addresses (or DNS names), the
<code><VirtualHost></code> supports this:
<pre>
<VirtualHost 1.2.3.4 5.6.7.8>
...
</VirtualHost>
</pre>
<p>
If, however, you want to specific the address to which the configuration
of the "server config" context, use <code>DefaultAddress</code>
(mentioned above).
<p>
There is one last configuration directive about which an administrator should
know: <a href="http://www.proftpd.org/docs/directives/linked/config_ref_SocketBindTight.html"><code>SocketBindTight</code></a>. By default, the
<code>proftpd</code> daemon will listen on all addresses, port 21, for the
connection requests of remote clients. Sometimes, the administrator may
wish to have the <code>proftpd</code> daemon listen <b>only</b> on the IP
addresses for which it has been configured, and not <i>every</i> address.
To accomplish this, simply use the <a href="http://www.proftpd.org/docs/directives/linked/config_ref_SocketBindTight.html"><code>SocketBindTight</code></a> configuration directive:
<pre>
SocketBindTight on
</pre>
This configures the daemon to "bind tightly" only to those IP
addresses to which it has been configured to listen, rather than every address.
By default, the <code>proftpd</code> daemon will listen to every address on
the host machine.
<p><a name="FAQ"></a>
<b>Frequently Asked Questions</b><br>
<p>
<font color=red>Question</font>: Why do I see the following when I start <code>proftpd</code>?<br>
<pre>
- warning: "Virtual Server" address/port (1.2.3.4:21) already in use by "Main Server"
</pre>
<font color=blue>Answer</font>: This happens when a <code><VirtualHost></code> section is "hidden" behind the default server in the "server config"
section (<i>i.e.</i> the context that is outside of all <code><VirtualHost></code> and <code><Global></code> sections). It is "hidden" because
both the <code><VirtualHost></code> section and the "server config"
section are using the same IP address and port.
<p>
It is quite common to configure <code><VirtualHost></code> sections
using DNS names, rather than IP addresses. And the "server config" section
in the <code>proftpd.conf</code> file, by default, uses the IP address of
the machine's hostname. This makes it quite easy to inadvertently have
multiple sections trying to use the same IP address and port.
<p>
The quick-and-easy fix is to place the following your "server config" section
in your <code>proftpd.conf</code>:
<pre>
Port 0
</pre>
as mentioned above. You can also use the <code>DefaultAddress</code>
directive in the "server config" section to explicitly tell the "server config"
section to use a different IP address/DNS name.
<p>
<font color=red>Question</font>: How can I have my "server config" section
(or a <code><VirtualHost></code> section) listen for multiple IP
addresses/DNS names?<br>
<font color=blue>Answer</font>: In version 1.3.0rc1 and later, the
<code><VirtualHost></code> configuration was enhanced so that it could
handle multiple IP addresses/DNS names, <i>e.g.</i>:
<pre>
<VirtualHost 1.2.3.4 ftp.example.com>
...
</VirtualHost>
</pre>
And for the "server config" context, you would use the
<code>DefaultAddress</code> directive, which can also handle multiple IP
addresses/DNS names:
<pre>
DefaultAddress 1.2.3.4 ftp.example.com
</pre>
<hr>
Last Updated: <i>$Date: 2009-01-12 23:41:26 $</i><br>
<hr>
</body>
</html>
|