* doc/guide.tex: Improve documentation of host_config

add (EJAB-544)
* doc/guide.html: Likewise
* src/ejabberd.cfg.example: Likewise
* src/ejabberd_config.erl: Likewise

SVN Revision: 1219

ChangeLog

@@ -1,5 +1,11 @@
 2008-03-04  Badlop  <badlop@process-one.net>
 
+	* doc/guide.tex: Improve documentation of host_config
+	add (EJAB-544)
+	* doc/guide.html: Likewise
+	* src/ejabberd.cfg.example: Likewise
+	* src/ejabberd_config.erl: Likewise
+
 	* doc/guide.tex: mod_announce recommends, but doesn't require
 	mod_adhoc (thanks to Anastasia Gornostaeva)
 	* doc/guide.html: Likewise

doc/guide.html

@@ -552,18 +552,16 @@ while domain <TT>example.com</TT> is using the LDAP servers running on the domai
                               {ldap_rootdn, "dc=localdomain"},
                               {ldap_rootdn, "dc=example,dc=com"},
                               {ldap_password, ""}]}.
-</PRE></LI></UL><P>If you have several virtual hosts, 
-and you want to define options such as <TT>modules</TT>
-with values specific for some virtual host, 
-instead of defining each option with the syntax
+</PRE></LI></UL><P>To define specific ejabberd modules in a virtual host,
+you can define the global <TT>modules</TT> option with the common modules,
+and later add specific modules to certain virtual hosts.
+To accomplish that, instead of defining each option in <TT>host_config</TT> with the syntax
 </P><PRE CLASS="verbatim">  {&lt;option-name&gt;, &lt;option-value&gt;}
 </PRE><P>you must use this syntax:
 </P><PRE CLASS="verbatim">  {{add, &lt;option-name&gt;}, &lt;option-value&gt;}
-</PRE><P>Example:
-</P><UL CLASS="itemize"><LI CLASS="li-itemize">
-	In this example three virtual hosts have some similar modules, but there are also
-	other different modules for some specific virtual hosts:
-<PRE CLASS="verbatim">% This ejabberd server has three vhosts:
+</PRE><P>In this example three virtual hosts have some similar modules, but there are also
+other different modules for some specific virtual hosts:
+</P><PRE CLASS="verbatim">% This ejabberd server has three vhosts:
 {hosts, ["one.example.org", "two.example.org", "three.example.org"]}.
 
 % Configuration of modules that are common to all vhosts
@@ -589,7 +587,7 @@ instead of defining each option with the syntax
 {host_config, "two.example.org", [{{add, modules}, [
   {mod_echo,       [{host, "mirror.two.example.org"}]}
 ]}]}.
-</PRE></LI></UL><!--TOC subsection Listening Ports-->
+</PRE><!--TOC subsection Listening Ports-->
 <H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc22">3.1.3</A>&#XA0;&#XA0;Listening Ports</H3><!--SEC END --><P>
 <A NAME="listened"></A>
 </P><P>The option <TT>listen</TT> defines for which addresses and ports <TT>ejabberd</TT>

doc/guide.tex

@@ -591,22 +591,20 @@ Examples:
 \end{verbatim}
 \end{itemize}
  
-If you have several virtual hosts, 
-and you want to define options such as \term{modules}
-with values specific for some virtual host, 
-instead of defining each option with the syntax
+To define specific ejabberd modules in a virtual host,
+you can define the global \term{modules} option with the common modules,
+and later add specific modules to certain virtual hosts.
+To accomplish that, instead of defining each option in \term{host\_config} with the syntax
 \begin{verbatim}
   {<option-name>, <option-value>}
 \end{verbatim}
-you must use this syntax:
+use this syntax:
 \begin{verbatim}
   {{add, <option-name>}, <option-value>}
 \end{verbatim}
 
-Example:
-\begin{itemize}
-	\item In this example three virtual hosts have some similar modules, but there are also
-	other different modules for some specific virtual hosts:
+In this example three virtual hosts have some similar modules, but there are also
+other different modules for some specific virtual hosts:
 \begin{verbatim}
 % This ejabberd server has three vhosts:
 {hosts, ["one.example.org", "two.example.org", "three.example.org"]}.
@@ -635,7 +633,6 @@ Example:
   {mod_echo,       [{host, "mirror.two.example.org"}]}
 ]}]}.
 \end{verbatim}
-\end{itemize}
 
 \subsection{Listening Ports}
 \label{listened}

src/ejabberd.cfg.example

@@ -341,6 +341,15 @@
 %%{acl, test, {user_regexp, "^test"}}.
 %%{acl, test, {user_glob, "test*"}}.
 
+%%
+%% Define specific ACLs in a virtual host.
+%%
+%%{host_config, "localhost",
+%% [
+%%  {acl, admin, {user, "bob-local", "localhost"}}
+%% ]
+%%}.
+
 
 %%%   ============
 %%%   ACCESS RULES
@@ -381,6 +390,16 @@
 %% Everybody can create pubsub nodes
 {access, pubsub_createnode, [{allow, all}]}.
 
+%%
+%% Define specific Access rules in a virtual host.
+%%
+%%{host_config, "localhost",
+%% [
+%%  {access, c2s, [{allow, admin}, {deny, all}]},
+%%  {access, register, [{deny, all}]}
+%% ]
+%%}.
+
 
 %%%   ================
 %%%   DEFAULT LANGUAGE
@@ -390,6 +409,13 @@
 %%
 {language, "en"}.
 
+%%
+%% Set a different language in a virtual host.
+%%
+%%{host_config, "localhost",
+%% [{language, "ru"}]
+%%}.
+
 
 %%%   =======
 %%%   MODULES
@@ -448,6 +474,17 @@
   {mod_version,  []}
  ]}.
 
+%%
+%% Enable modules with custom options in a specific virtual host
+%%
+%%{host_config, "localhost",
+%% [{{add, modules},
+%%   [
+%%    {mod_echo, [{host, "mirror.localhost"}]}
+%%   ]
+%%  }
+%% ]}.
+
 
 %%% $Id$
 

src/ejabberd_config.erl

@@ -211,11 +211,16 @@ add_option(Opt, Val, State) ->
 	    end
     end.
 
-compact(Opt, Val, [], Os) ->
+compact({OptName, Host} = Opt, Val, [], Os) ->
+    ?WARNING_MSG("The option '~p' is defined for the host ~p using host_config "
+    "before the global '~p' option. This host_config option may get overwritten.", [OptName, Host, OptName]),
     [#local_config{key = Opt, value = Val}] ++ Os;
+%% Traverse the list of the options already parsed
 compact(Opt, Val, [O | Os1], Os2) ->
-    case O#local_config.key of
+    case catch O#local_config.key of
+	%% If the key of a local_config matches the Opt that wants to be added
 	Opt ->
+	    %% Then prepend the new value to the list of old values
 	    Os2 ++ [#local_config{key = Opt,
 				  value = Val++O#local_config.value}
 		   ] ++ Os1;