From 97da380acd8e3ba0c9a9618a99c4106eca1d1576 Mon Sep 17 00:00:00 2001 From: Evgeny Khramtsov Date: Wed, 8 Jan 2020 12:24:51 +0300 Subject: Generate ejabberd.yml.5 man page from source code directly Several documentation callbacks (doc/0 and mod_doc/0) are implemented and `ejabberdctl man` command is added to generate a man page. Note that the command requires a2x to be installed (which is a part of asciidoc package). --- src/mod_proxy65.erl | 149 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 148 insertions(+), 1 deletion(-) (limited to 'src/mod_proxy65.erl') diff --git a/src/mod_proxy65.erl b/src/mod_proxy65.erl index 718f49cb..d682e6c6 100644 --- a/src/mod_proxy65.erl +++ b/src/mod_proxy65.erl @@ -39,7 +39,7 @@ %% supervisor callbacks. -export([init/1]). --export([start_link/1, mod_opt_type/1, mod_options/1, depends/2]). +-export([start_link/1, mod_opt_type/1, mod_options/1, depends/2, mod_doc/0]). -define(PROCNAME, ejabberd_mod_proxy65). @@ -139,3 +139,150 @@ mod_options(Host) -> {recbuf, 65536}, {sndbuf, 65536}, {shaper, none}]. + +mod_doc() -> + #{desc => + ?T("This module implements " + "https://xmpp.org/extensions/xep-0065.html" + "[XEP-0065: SOCKS5 Bytestreams]. It allows ejabberd " + "to act as a file transfer proxy between two XMPP clients."), + opts => + [{host, + #{desc => ?T("Deprecated. Use 'hosts' instead.")}}, + {hosts, + #{value => ?T("[Host, ...]"), + desc => + ?T("This option defines the Jabber IDs of the service. " + "If the 'hosts' option is not specified, the only Jabber ID will " + "be the hostname of the virtual host with the prefix \"proxy.\". " + "The keyword '@HOST@' is replaced with the real virtual host name.")}}, + {name, + #{value => ?T("Name"), + desc => + ?T("The value of the service name. This name is only visible in some " + "clients that support https://xmpp.org/extensions/xep-0030.html" + "[XEP-0030: Service Discovery]. The default is \"SOCKS5 Bytestreams\".")}}, + {access, + #{value => ?T("AccessName"), + desc => + ?T("Defines an access rule for file transfer initiators. " + "The default value is 'all'. You may want to restrict " + "access to the users of your server only, in order to " + "avoid abusing your proxy by the users of remote " + "servers.")}}, + {ram_db_type, + #{value => "mnesia | redis | sql", + desc => + ?T("Define the type of volatile (in-memory) storage where the module " + "will store room information.")}}, + {ip, + #{value => ?T("IPAddress"), + desc => + ?T("This option specifies which network interface to listen " + "for. The default value is an IP address of the service's " + "DNS name, or, if fails, '127.0.0.1'.")}}, + {hostname, + #{value => ?T("Host"), + desc => + ?T("Defines a hostname offered by the proxy when " + "establishing a session with clients. This is useful " + "when you run the proxy behind a NAT. The keyword " + "'@HOST@' is replaced with the virtual host name. " + "The default is to use the value of 'ip' option. " + "Examples: 'proxy.mydomain.org', '200.150.100.50'.")}}, + {port, + #{value => "1..65535", + desc => + ?T("A port number to listen for incoming connections. " + "The default value is '7777'.")}}, + {auth_type, + #{value => "anonymous | plain", + desc => + ?T("SOCKS5 authentication type. " + "The default value is 'anonymous'. " + "If set to 'plain', ejabberd will use " + "authentication backend as it would " + "for SASL PLAIN.")}}, + {max_connections, + #{value => "pos_integer() | infinity", + desc => + ?T("Maximum number of active connections per file transfer " + "initiator. The default value is 'infinity'.")}}, + {shaper, + #{value => ?T("Shaper"), + desc => + ?T("This option defines a shaper for the file transfer peers. " + "A shaper with the maximum bandwidth will be selected. " + "The default is 'none', i.e. no shaper.")}}, + {recbuf, + #{value => ?T("Size"), + desc => + ?T("A size of the buffer for incoming packets. " + "If you define a shaper, set the value of this " + "option to the size of the shaper in order " + "to avoid traffic spikes in file transfers. " + "The default value is '65536' bytes.")}}, + {sndbuf, + #{value => ?T("Size"), + desc => + ?T("A size of the buffer for outgoing packets. " + "If you define a shaper, set the value of this " + "option to the size of the shaper in order " + "to avoid traffic spikes in file transfers. " + "The default value is '65536' bytes.")}}, + {vcard, + #{value => ?T("vCard"), + desc => + ?T("A custom vCard of the service that will be displayed " + "by some XMPP clients in Service Discovery. The value of " + "'vCard' is a YAML map constructed from an XML representation " + "of vCard. Since the representation has no attributes, " + "the mapping is straightforward."), + example => + [{?T("For example, the following XML representation of vCard:"), + ["", + " Conferences", + " ", + " ", + " Elm Street", + " ", + ""]}, + {?T("will be translated to:"), + ["vcard:", + " fn: Conferences", + " adr:", + " -", + " work: true", + " street: Elm Street"]}]}}], + example => + ["acl:", + " admin:", + " user: admin@example.org", + " proxy_users:", + " server: example.org", + "", + "access_rules:", + " proxy65_access:", + " allow: proxy_users", + "", + "shaper_rules:", + " proxy65_shaper:", + " none: admin", + " proxyrate: proxy_users", + "", + "shaper:", + " proxyrate: 10240", + "", + "modules:", + " ...", + " mod_proxy65:", + " host: proxy1.example.org", + " name: \"File Transfer Proxy\"", + " ip: 200.150.100.1", + " port: 7778", + " max_connections: 5", + " access: proxy65_access", + " shaper: proxy65_shaper", + " recbuf: 10240", + " sndbuf: 10240", + " ..."]}. -- cgit v1.2.3