* src/ejabberd.cfg.example: Huge reorganization and grouping of options (EJAB-392).

SVN Revision: 982

1 files changed, 374 insertions, 155 deletions

diff --git a/src/ejabberd.cfg.example b/src/ejabberd.cfg.example
index e3988c9d..9b61e61b 100644
--- a/src/ejabberd.cfg.example
+++ b/src/ejabberd.cfg.example
@@ -1,201 +1,420 @@
-% $Id$
-
-% ejabberd loglevel (0: no log -> 5: debug)
+%%%
+%%%               ejabberd configuration file
+%%%
+
+%%% The parameters used in this configuration file are explained in more detail
+%%% in the ejabberd Installation and Operation Guide.
+%%% Please consult the Guide in case of doubts, it is included in 
+%%% your copy of ejabberd, and is also available online at
+%%% http://www.process-one.net/en/ejabberd/docs/
+
+%%% This configuration file contains Erlang terms.
+%%% In case you want to understand the syntax, here are the concepts:
+%%%
+%%%  - The character to comment a line is %
+%%%
+%%%  - Each term ends in a dot, for example:
+%%%      override_global.
+%%%
+%%%  - A tuple has a fixed definition, its elements are 
+%%%    enclosed in {}, and separated with commas:
+%%%      {loglevel, 4}.
+%%%
+%%%  - A list can have as many elements as you want, 
+%%%    and is enclosed in [], for example:
+%%%      [http_poll, web_admin, tls]
+%%%
+%%%  - A keyword of ejabberd is a word in lowercase. 
+%%%    The strings are enclosed in "" and can have spaces, dots...
+%%%      {language, "en"}.
+%%%      {ldap_rootdn, "dc=example,dc=com"}. 
+%%%
+%%%  - This term includes a tuple, a keyword, a list and two strings:
+%%%      {hosts, ["jabber.example.net", "im.example.com"]}.
+%%%
+
+
+%%%   =======================
+%%%   OVERRIDE STORED OPTIONS
+
+%%
+%% Override the old values stored in the database.
+%%
+
+%%
+%% Override global options (shared by all ejabberd nodes in a cluster).
+%%
+%%override_global.
+
+%%
+%% Override local options (specific for this particular ejabberd node).
+%%
+%%override_local.
+
+%%
+%% Remove the Access Control Lists before new ones are added.
+%%
+%%override_acls.
+
+
+%%%   =========
+%%%   DEBUGGING
+
+%%
+%% loglevel: Verbosity of log files generated by ejabberd.
+%% 0: No ejabberd log at all (not recommended)
+%% 1: Critical
+%% 2: Error
+%% 3: Warning
+%% 4: Info
+%% 5: Debug
+%%
 {loglevel, 4}.
 
-%override_acls.
-% Users that have admin access.  Add line like one of the following after you
-% will be successfully registered on server to get admin access:
-%{acl, admin, {user, "aleksey"}}.
-%{acl, admin, {user, "ermine"}}.
+%%
+%% watchdog_admins: If an ejabberd process consumes too much memory, 
+%% send live notifications to those Jabber accounts.
+%%
+%%{watchdog_admins, ["bob@example.com"]}.
 
-% Blocked users:
-%{acl, blocked, {user, "test"}}.
 
-% Local users:
-{acl, local, {user_regexp, ""}}.
+%%%   ================
+%%%   SERVED HOSTNAMES
 
-% Another examples of ACLs:
-%{acl, jabberorg, {server, "jabber.org"}}.
-%{acl, aleksey, {user, "aleksey", "jabber.ru"}}.
-%{acl, test, {user_regexp, "^test"}}.
-%{acl, test, {user_glob, "test*"}}.
+%%
+%% hosts: Domains served by ejabberd.
+%% You can define one or several, for example:
+%% {hosts, ["example.net", "example.com", "example.org"]}.
+%%
+{hosts, ["localhost"]}.
 
-% Everybody can create pubsub nodes
-{access, pubsub_createnode, [{allow, all}]}.
+%%
+%% route_subdomains: Delegate subdomains to other Jabber server.
+%% For example, if this ejabberd serves example.org and you want
+%% to allow communication with a Jabber server called im.example.org.
+%%
+%%{route_subdomains, s2s}.
 
-% Only admins can use configuration interface:
-{access, configure, [{allow, admin}]}.
 
-% Every username can be registered via in-band registration:
-% You could replace {allow, all} with {deny, all} to prevent user from using
-% in-band registration
-{access, register, [{allow, all}]}.
+%%%   ===============
+%%%   LISTENING PORTS
 
-% Debug: 
-% watchdog admins receive live notifications on ejabberd process consuming too
-% much memory
-% {watchdog_admins, ["admin1@localhost"]}.
+%%
+%% listen: Which ports will ejabberd listen, which service handles it
+%% and what options to start it with.
+%%
+{listen,
+ [
 
-% Only admins can send announcement messages:
-{access, announce, [{allow, admin}]}.
+  {5222, ejabberd_c2s, [
+
+			%%
+			%% If TLS is compiled and you installed a SSL
+			%% certificate, put the correct path to the 
+			%% file and uncomment this line:
+			%%
+			%%{certfile, "/path/to/ssl.pem"}, starttls,
+
+			{access, c2s},
+			{shaper, c2s_shaper},
+			{max_stanza_size, 65536}
+		       ]},
+
+  %%
+  %% To enable the old SSL connection method in port 5223:
+  %%
+  %%{5223, ejabberd_c2s, [
+  %%			{access, c2s},
+  %%			{shaper, c2s_shaper},
+  %%			tls, {certfile, "/path/to/ssl.pem"},
+  %%			{max_stanza_size, 65536}
+  %%		       ]},
+
+  {5269, ejabberd_s2s_in, [
+			   {shaper, s2s_shaper},
+			   {max_stanza_size, 131072}
+			  ]},
+
+  %%
+  %% ejabberd_service: Interact with external components (transports...)
+  %%
+  %%{8888, ejabberd_service, [
+  %%			    {access, all}, 
+  %%			    {shaper_rule, fast},
+  %%			    {ip, {127, 0, 0, 1}},
+  %%			    {hosts, ["icq.example.org", "sms.example.org"],
+  %%			     [{password, "secret"}]
+  %%			    }
+  %%			   ]},
+
+  {5280, ejabberd_http, [
+			 http_poll, 
+			 web_admin
+			]}
 
+ ]}.
 
-% Only non-blocked users can use c2s connections:
-{access, c2s, [{deny, blocked},
-	       {allow, all}]}.
+%%
+%% s2s_use_starttls: Enable STARTTLS + Dialback for S2S connections.
+%% Allowed values are: true or false.
+%% You must specify a certificate file.
+%%
+%%{s2s_use_starttls, true}.
+
+%%
+%% s2s_certfile: Specify a certificate file.
+%%
+%%{s2s_certfile, "/path/to/ssl.pem"}.
+
+%%
+%% domain_certfile: Specify a different certificate for each served hostname.
+%%
+%%{domain_certfile, "example.org", "/path/to/example_org.pem"}.
+%%{domain_certfile, "example.com", "/path/to/example_com.pem"}.
+
+%%
+%% S2S whitelist or blacklist
+%%
+%% Default s2s policy for undefined hosts.
+%%
+%%{s2s_default_policy, allow}.
+
+%%
+%% Allow or deny communication with specific servers.
+%%
+%%{{s2s_host, "goodhost.org"}, allow}.
+%%{{s2s_host, "badhost.org"}, deny}.
+
+
+%%%   ==============
+%%%   AUTHENTICATION
+
+%%
+%% auth_method: Method used to authenticate the users.
+%% The default method is the internal.
+%% If you want to use a different method, 
+%% comment this line and enable the correct ones.
+%%
+{auth_method, internal}.
 
-% Set shaper with name "normal" to limit traffic speed to 1000B/s
-{shaper, normal, {maxrate, 1000}}.
+%%
+%% Authentication using external script
+%% Make sure the script is executable by ejabberd.
+%%
+%%{auth_method, external}.
+%%{extauth_program, "/path/to/authentication/script"}.
+
+%%
+%% Authentication using PAM
+%%
+%%{auth_method, pam}.
+%%{pam_service, "pamservicename"}.
+
+%%
+%% Authentication using LDAP
+%%
+%%{auth_method, ldap}.
+%%
+%% List of LDAP servers:
+%%{ldap_servers, ["localhost"]}.    
+%%
+%% LDAP attribute that holds user ID:
+%%{ldap_uids, [{"mail", "%u@mail.example.org"}]}. 
+%%
+%% Search base of LDAP directory:
+%%{ldap_base, "dc=example,dc=com"}. 
+%%
+%% LDAP manager:
+%%{ldap_rootdn, "dc=example,dc=com"}. 
+%%
+%% Password to LDAP manager:
+%%{ldap_password, "******"}. 
+
+%%
+%% Authentication using ODBC
+%%
+%%{auth_method, odbc}.
+%%{odbc_server, "DSN=ejabberd;UID=ejabberd;PWD=ejabberd"}.
+
+%%
+%% If you use PostgreSQL, have a large database, and need a
+%% faster but inexact replacement for "select count(*) from users"
+%%
+%%{pgsql_users_number_estimate, true}.
+
+%%
+%% Anonymous login support:
+%%   auth_method: anonymous
+%%   anonymous_protocol: sasl_anon | login_anon | both
+%%   allow_multiple_connections: true | false
+%%
+%%{host_config, "public.example.org", [{auth_method, anonymous},
+%%                                     {allow_multiple_connections, false},
+%%                                     {anonymous_protocol, sasl_anon}]}.
+%%
+%% To use both anonymous and internal authentication:
+%%
+%%{host_config, "public.example.org", [{auth_method, [internal, anonymous]}]}.
 
-% Set shaper with name "fast" to limit traffic speed to 50000B/s
-{shaper, fast, {maxrate, 50000}}.
 
-% For all users except admins used "normal" shaper
-{access, c2s_shaper, [{none, admin},
-		      {normal, all}]}.
+%%%   ================
+%%%   DATABASE STORAGE
 
-% For all S2S connections used "fast" shaper
-{access, s2s_shaper, [{fast, all}]}.
+%% ejabberd uses by default the internal Mnesia database.
+%% For instructions about using other database backends,
+%% please consult the ejabberd Guide.
 
-% Admins of this server are also admins of MUC service:
-{access, muc_admin, [{allow, admin}]}.
 
-% All users are allowed to use MUC service:
-{access, muc, [{allow, all}]}.
+%%%   ===============
+%%%   TRAFFIC SHAPERS
 
-% This rule allows access only for local users:
-{access, local, [{allow, local}]}.
+%%
+%% The "normal" shaper limits traffic speed to 1.000 B/s
+%%
+{shaper, normal, {maxrate, 1000}}.
 
+%%
+%% The "fast" shaper limits traffic speed to 50.000 B/s
+%%
+{shaper, fast, {maxrate, 50000}}.
 
-% Authentication method.  If you want to use internal user base, then use
-% this line:
-{auth_method, internal}.
 
-% For LDAP authentication use these lines instead of above one:
-%{auth_method, ldap}.
-%{ldap_servers, ["localhost"]}.    % List of LDAP servers
-%{ldap_uidattr, "uid"}.            % LDAP attribute that holds user ID
-%{ldap_base, "dc=example,dc=com"}. % Search base of LDAP directory
-%{ldap_rootdn, "dc=example,dc=com"}. % LDAP manager
-%{ldap_password, "******"}. % Password to LDAP manager
+%%%   ====================
+%%%   ACCESS CONTROL LISTS
 
-% For authentication via external script use the following:
-%{auth_method, external}.
-%{extauth_program, "/path/to/authentication/script"}.
+%%
+%% The 'admin' ACL grants administrative privileges to Jabber accounts.
+%% You can put as many accounts as you want.
+%%
+%%{acl, admin, {user, "aleksey", "localhost"}}.
+%%{acl, admin, {user, "ermine", "example.org"}}.
 
-% For authentication via PAM use the following:
-%{auth_method, pam}.
-%{pam_service, "pamservicename"}.
+%%
+%% Blocked users
+%%
+%%{acl, blocked, {user, "baduser", "example.org"}}.
+%%{acl, blocked, {user, "test"}}.
 
-% For authentication via ODBC use the following:
-%{auth_method, odbc}.
-%{odbc_server, "DSN=ejabberd;UID=ejabberd;PWD=ejabberd"}.
+%%
+%% Local users: don't modify this line.
+%%
+{acl, local, {user_regexp, ""}}.
 
-% Uncomment this if you are using postgres, having a large DB, and need a
-% faster but inexact replacement for "select count(*) from users"
-%{pgsql_users_number_estimate, true}.
+%%
+%% More examples of ACLs
+%%
+%%{acl, jabberorg, {server, "jabber.org"}}.
+%%{acl, aleksey, {user, "aleksey", "jabber.ru"}}.
+%%{acl, test, {user_regexp, "^test"}}.
+%%{acl, test, {user_glob, "test*"}}.
 
 
-% Host name:
-{hosts, ["localhost"]}.
+%%%   ============
+%%%   ACCESS RULES
 
 %% Define the maximum number of time a single user is allowed to connect:
 {access, max_user_sessions, [{10, all}]}.
 
-%% Anonymous login support:
-%%  auth_method: anonymous
-%%  anonymous_protocol: sasl_anon|login_anon|both
-%%  allow_multiple_connections: true|false
-%%{host_config, "public.example.org", [{auth_method, anonymous},
-%%                                     {allow_multiple_connections, false},
-%%                                     {anonymous_protocol, sasl_anon}]}.
-%% To use both anonymous and internal authentication:
-%%{host_config, "public.example.org", [{auth_method, [internal,anonymous]}]}.
+%% This rule allows access only for local users:
+{access, local, [{allow, local}]}.
 
-% Default language for server messages
-{language, "en"}.
+%% Only non-blocked users can use c2s connections:
+{access, c2s, [{deny, blocked},
+	       {allow, all}]}.
 
-% Listened ports:
-{listen,
- [{5222, ejabberd_c2s,     [{access, c2s}, {shaper, c2s_shaper},
-			    {max_stanza_size, 65536},
-			    starttls, {certfile, "./ssl.pem"}]},
-  {5223, ejabberd_c2s,     [{access, c2s},
-			    {max_stanza_size, 65536},
-			    tls, {certfile, "./ssl.pem"}]},
-  % Use these two lines instead if TLS support is not compiled
-  %{5222, ejabberd_c2s,     [{access, c2s}, {shaper, c2s_shaper}]},
-  %{5223, ejabberd_c2s,     [{access, c2s}, ssl, {certfile, "./ssl.pem"}]},
-  {5269, ejabberd_s2s_in,  [{shaper, s2s_shaper},
-			    {max_stanza_size, 131072}
-			   ]},
-  {5280, ejabberd_http,    [http_poll, web_admin]},
-  {8888, ejabberd_service, [{access, all}, {shaper_rule, fast},
-			    {hosts, ["icq.localhost", "sms.localhost"],
-			     [{password, "secret"}]}]}
- ]}.
+%% For all users except admins used "normal" shaper
+{access, c2s_shaper, [{none, admin},
+		      {normal, all}]}.
+
+%% For all S2S connections used "fast" shaper
+{access, s2s_shaper, [{fast, all}]}.
+
+%% Only admins can send announcement messages:
+{access, announce, [{allow, admin}]}.
 
+%% Only admins can use configuration interface:
+{access, configure, [{allow, admin}]}.
 
-% Use STARTTLS+Dialback for S2S connections
-{s2s_use_starttls, true}.
-{s2s_certfile, "./ssl.pem"}.
-%{domain_certfile, "example.org", "./example_org.pem"}.
-%{domain_certfile, "example.com", "./example_com.pem"}.
+%% Admins of this server are also admins of MUC service:
+{access, muc_admin, [{allow, admin}]}.
 
-%% S2S Whitelist or blacklist:
-%{s2s_default_policy, allow}. %% Default s2s policy for undefined hosts
-%%{{s2s_host,"goodhost.org"}, allow}.
-%{{s2s_host,"badhost.org"}, deny}. 
+%% All users are allowed to use MUC service:
+{access, muc, [{allow, all}]}.
 
-% If SRV lookup fails, then port 5269 is used to communicate with remote server
-{outgoing_s2s_port, 5269}.
+%% Every username can be registered via in-band registration:
+%% To disable in-band registration, replace 'allow' with 'deny'.
+{access, register, [{allow, all}]}.
 
+%% Everybody can create pubsub nodes
+{access, pubsub_createnode, [{allow, all}]}.
 
-% Used modules:
+
+%%%   ================
+%%%   DEFAULT LANGUAGE
+
+%%
+%% language: Default language used for server messages.
+%%
+{language, "en"}.
+
+
+%%%   =======
+%%%   MODULES
+
+%%
+%% Modules enabled in all ejabberd virtual hosts.
+%%
 {modules,
  [
-  {mod_register,   [
-	%% After successful registration user will get message with following subject and body:
-	%{welcome_message, {"Welcome!", "Welcome to this Jabber server."}},
-	%% List of people who will get notifications when users register
-	%{registration_watchers, ["admin1@example.org", "admin2@example.org"]},
-	{access, register}
-  ]},
-  {mod_roster,     []},
-  {mod_privacy,    []},
-  {mod_adhoc,      []},
-  {mod_configure,  []}, % Depends on mod_adhoc
-  {mod_configure2, []},
-  {mod_disco,      []},
-  {mod_stats,      []},
-  {mod_vcard,      []},
-  {mod_offline,    []},
-  {mod_announce,   [{access, announce}]}, % Depends on mod_adhoc
-  {mod_echo,       [{host, "echo.localhost"}]},
-  {mod_private,    []},
-  {mod_irc,        []},
-% Default options for mod_muc:
-%   host: "conference.@HOST@"
-%   access: all
-%   access_create: all
-%   access_persistent: all
-%   access_admin: none (only room creator has owner privileges)
-  {mod_muc,        [{access, muc},
-		    {access_create, muc},
-		    {access_persistent, muc},
-		    {access_admin, muc_admin}]},
-%  {mod_muc_log,    []},
-%  {mod_shared_roster, []},
-  {mod_pubsub,     [{access_createnode, pubsub_createnode}]},
-  {mod_time,       []},
-  {mod_last,       []},
-  {mod_version,    []}
+  {mod_adhoc,    []},
+  {mod_announce, [{access, announce}]}, % requires mod_adhoc
+  {mod_configure,[]}, % requires mod_adhoc
+  {mod_disco,    []},
+  %%{mod_echo,   [{host, "echo.localhost"}]},
+  {mod_irc,      []},
+  {mod_last,     []},
+  {mod_muc,      [
+		  %%{host, "conference.@HOST@"},
+		  {access, muc},
+		  {access_create, muc},
+		  {access_persistent, muc},
+		  {access_admin, muc_admin}
+		 ]},
+  %%{mod_muc_log,[]},
+  {mod_offline,  []},
+  {mod_privacy,  []},
+  {mod_private,  []},
+  %%{mod_proxy65,[]},
+  {mod_pubsub,   [{access_createnode, pubsub_createnode}]},
+  {mod_register, [
+		  %%
+		  %% After successful registration, the user receives 
+		  %% a message with this subject and body.
+		  %%
+		  {welcome_message, {"Welcome!", 
+				     "Welcome to this Jabber server."}},
+
+		  %%
+		  %% When a user registers, send a notification to 
+		  %% these Jabber accounts.
+		  %%
+		  %%{registration_watchers, ["admin1@example.org"]},
+
+		  {access, register}
+		 ]},
+  {mod_roster,   []},
+  %%{mod_service_log,[]},
+  {mod_shared_roster,[]},
+  {mod_stats,    []},
+  {mod_time,     []},
+  {mod_vcard,    []},
+  {mod_version,  []}
  ]}.
 
 
+%%% $Id$
 
-
-% Local Variables:
-% mode: erlang
-% End:
+%%% Local Variables:
+%%% mode: erlang
+%%% End:
+%%% vim: set filetype=erlang tabstop=8: