From 146adce3d6dcc332cd04413c9eddbf4360e64cab Mon Sep 17 00:00:00 2001
From: Badlop <badlop@process-one.net>
Date: Thu, 15 Jan 2015 20:00:35 +0100
Subject: [PATCH] Update the Guide about using access_commands in YAML/CFG
 files

---
 doc/guide.tex | 46 +++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 39 insertions(+), 7 deletions(-)

diff --git a/doc/guide.tex b/doc/guide.tex
index 106641710..5e0ec7694 100644
--- a/doc/guide.tex
+++ b/doc/guide.tex
@@ -5403,15 +5403,10 @@ The \term{ejabberdctl commands} are:
 
 The \term{ejabberdctl} script can be restricted to require authentication
 and execute some \term{ejabberd commands}; see \ref{accesscommands}.
-Add the option to the file \term{ejabberd.yml}.
-In this example there is no restriction:
-\begin{verbatim}
-ejabberdctl_access_commands: []
-\end{verbatim}
 
 If account \term{robot1@example.org} is registered in \ejabberd{} with password \term{abcdef}
 (which MD5 is E8B501798950FC58AAD83C8C14978E),
-and \term{ejabberd.yml} contains this setting:
+and your old-format configuration file contains this setting:
 \begin{verbatim}
 {hosts, ["example.org"]}.
 {acl, bots, {user, "robot1", "example.org"}}.
@@ -5599,8 +5594,17 @@ The most interesting ones are:
 
 \makesubsection{accesscommands}{Restrict Execution with AccessCommands}
 
-The frontends can be configured to restrict access to certain commands.
+The frontends can be configured to restrict access to certain commands
+using the \term{AccessCommands}.
 In that case, authentication information must be provided.
+
+This option allows quite complex settings, so it does not use the YAML format,
+instead it uses the Erlang format.
+If you want to set that option,
+then you must move the frontend definition to another config file
+and include it using the \term{include\_config\_file} option
+(see section~\ref{includeconfigfile} and the example below).
+
 In each frontend the \term{AccessCommands} option is defined
 in a different place. But in all cases the option syntax is the same:
 \begin{verbatim}
@@ -5658,6 +5662,34 @@ See another list of restrictions (the corresponding ACL and ACCESS are not shown
 ]
 \end{verbatim}
 
+In summary, you put the frontends configurations in a CFG file using Erlang format, for example a file called \term{additional.cfg}:
+\begin{verbatim}
+{ejabberdctl_access_commands, [ {ctlaccess, [registered_users, register], []} ]}.
+
+{listen, [
+  {4560, ejabberd_xmlrpc, [{maxsessions, 10}, {timeout, 5000},
+    {access_commands, [
+      {ctlaccess, [registered_users], [{host, "localhost"}]}
+    ]}
+  ]}
+ ]}.
+
+{modules, [
+  {mod_rest, [
+    {allowed_ips, [ {127,0,0,1}, {192,168,1,12} ]},
+    {allowed_destinations, [ "nolan@localhost", "admin@example.com" ]},
+    {allowed_stanza_types, [ "message", "presence", "iq" ]},
+    {access_commands, [
+      {ctlaccess, [registered_users], [{host, "localhost"}]}
+    ]}
+   ]}
+ ]}.
+\end{verbatim}
+and then add this line at the end of your main ejabberd configuration file, usually called \term{ejabberd.yml}:
+\begin{verbatim}
+include_config_file: "/etc/ejabberd/additional.cfg"
+\end{verbatim}
+
 \makesection{webadmin}{Web Admin}
 \ind{web admin}