From cc14e223c62d15e317d23850ac482620e852b04a Mon Sep 17 00:00:00 2001 From: Badlop Date: Mon, 12 Dec 2016 13:18:31 +0100 Subject: [PATCH] Describe command arguments and results in ejabberd_admin --- src/ejabberd_admin.erl | 83 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 77 insertions(+), 6 deletions(-) diff --git a/src/ejabberd_admin.erl b/src/ejabberd_admin.erl index 9592c2702..5bf8e3bab 100644 --- a/src/ejabberd_admin.erl +++ b/src/ejabberd_admin.erl @@ -76,6 +76,9 @@ get_commands_spec() -> #ejabberd_commands{name = status, tags = [server], desc = "Get status of the ejabberd server", module = ?MODULE, function = status, + result_desc = "Result tuple", + result_example = {ok, <<"The node ejabberd@localhost is started with status: started" + "ejabberd X.X is running in that node">>}, args = [], result = {res, restuple}}, #ejabberd_commands{name = stop, tags = [server], desc = "Stop ejabberd gracefully", @@ -101,11 +104,15 @@ get_commands_spec() -> "ejabberdctl stop_kindly 60 " "\\\"The server will stop in one minute.\\\"", module = ?MODULE, function = stop_kindly, + args_desc = ["Seconds to wait", "Announcement to send, with quotes"], + args_example = [60, <<"Server will stop now.">>], args = [{delay, integer}, {announcement, string}], result = {res, rescode}}, #ejabberd_commands{name = get_loglevel, tags = [logs, server], desc = "Get the current loglevel", module = ejabberd_logger, function = get, + result_desc = "Tuple with the log level number, its keyword and description", + result_example = {4, <<"info">>, <<"Info">>}, args = [], result = {leveltuple, {tuple, [{levelnumber, integer}, {levelatom, atom}, @@ -114,6 +121,10 @@ get_commands_spec() -> #ejabberd_commands{name = set_loglevel, tags = [logs, server], desc = "Set the loglevel (0 to 5)", module = ?MODULE, function = set_loglevel, + args_desc = ["Integer of the desired logging level, between 1 and 5"], + args_example = [5], + result_desc = "The type of logger module used", + result_example = lager, args = [{loglevel, integer}], result = {logger, atom}}, @@ -121,10 +132,12 @@ get_commands_spec() -> desc = "List modified modules that can be updated", module = ?MODULE, function = update_list, args = [], + result_example = ["mod_configure", "mod_vcard"], result = {modules, {list, {module, string}}}}, #ejabberd_commands{name = update, tags = [server], desc = "Update the given module, or use the keyword: all", module = ?MODULE, function = update, + args_example = ["mod_vcard"], args = [{module, string}], result = {res, restuple}}, @@ -132,22 +145,32 @@ get_commands_spec() -> desc = "Register a user", policy = admin, module = ?MODULE, function = register, + args_desc = ["Username", "Local vhost served by ejabberd", "Password"], + args_example = [<<"bob">>, <<"example.com">>, <<"SomEPass44">>], args = [{user, binary}, {host, binary}, {password, binary}], result = {res, restuple}}, #ejabberd_commands{name = unregister, tags = [accounts], desc = "Unregister a user", policy = admin, module = ?MODULE, function = unregister, + args_desc = ["Username", "Local vhost served by ejabberd"], + args_example = [<<"bob">>, <<"example.com">>], args = [{user, binary}, {host, binary}], result = {res, restuple}}, #ejabberd_commands{name = registered_users, tags = [accounts], desc = "List all registered users in HOST", module = ?MODULE, function = registered_users, + args_desc = ["Local vhost"], + args_example = [<<"example.com">>], + result_desc = "List of registered accounts usernames", + result_example = [<<"user1">>, <<"user2">>], args = [{host, binary}], result = {users, {list, {username, string}}}}, #ejabberd_commands{name = registered_vhosts, tags = [server], desc = "List all registered vhosts in SERVER", module = ?MODULE, function = registered_vhosts, + result_desc = "List of available vhosts", + result_example = [<<"example.com">>, <<"anon.example.com">>], args = [], result = {vhosts, {list, {vhost, string}}}}, #ejabberd_commands{name = reload_config, tags = [server], @@ -159,59 +182,85 @@ get_commands_spec() -> #ejabberd_commands{name = join_cluster, tags = [cluster], desc = "Join this node into the cluster handled by Node", module = ?MODULE, function = join_cluster, + args_desc = ["Nodename of the node to join"], + args_example = [<<"ejabberd1@machine7">>], args = [{node, binary}], result = {res, rescode}}, #ejabberd_commands{name = leave_cluster, tags = [cluster], - desc = "Remove node handled by Node from the cluster", + desc = "Remove and shutdown Node from the running cluster", + longdesc = "This command can be run from any running node of the cluster, " + "even the node to be removed.", module = ?MODULE, function = leave_cluster, + args_desc = ["Nodename of the node to kick from the cluster"], + args_example = [<<"ejabberd1@machine8">>], args = [{node, binary}], result = {res, rescode}}, + #ejabberd_commands{name = list_cluster, tags = [cluster], desc = "List nodes that are part of the cluster handled by Node", module = ?MODULE, function = list_cluster, + result_example = [ejabberd1@machine7, ejabberd1@machine8], args = [], result = {nodes, {list, {node, atom}}}}, #ejabberd_commands{name = import_file, tags = [mnesia], desc = "Import user data from jabberd14 spool file", module = ?MODULE, function = import_file, + args_desc = ["Full path to the jabberd14 spool file"], + args_example = ["/var/lib/ejabberd/jabberd14.spool"], args = [{file, string}], result = {res, restuple}}, #ejabberd_commands{name = import_dir, tags = [mnesia], desc = "Import users data from jabberd14 spool dir", module = ?MODULE, function = import_dir, + args_desc = ["Full path to the jabberd14 spool directory"], + args_example = ["/var/lib/ejabberd/jabberd14/"], args = [{file, string}], result = {res, restuple}}, #ejabberd_commands{name = import_piefxis, tags = [mnesia], desc = "Import users data from a PIEFXIS file (XEP-0227)", module = ejabberd_piefxis, function = import_file, + args_desc = ["Full path to the PIEFXIS file"], + args_example = ["/var/lib/ejabberd/example.com.xml"], args = [{file, string}], result = {res, rescode}}, #ejabberd_commands{name = export_piefxis, tags = [mnesia], desc = "Export data of all users in the server to PIEFXIS files (XEP-0227)", module = ejabberd_piefxis, function = export_server, + args_desc = ["Full path to a directory"], + args_example = ["/var/lib/ejabberd/"], args = [{dir, string}], result = {res, rescode}}, #ejabberd_commands{name = export_piefxis_host, tags = [mnesia], desc = "Export data of users in a host to PIEFXIS files (XEP-0227)", module = ejabberd_piefxis, function = export_host, + args_desc = ["Full path to a directory", "Vhost to export"], + args_example = ["/var/lib/ejabberd/", "example.com"], args = [{dir, string}, {host, string}], result = {res, rescode}}, #ejabberd_commands{name = delete_mnesia, tags = [mnesia, sql], - desc = "Export all tables as SQL queries to a file", + desc = "Delete elements in Mnesia database for a given vhost", module = ejd2sql, function = delete, + args_desc = ["Vhost which content will be deleted in Mnesia database"], + args_example = ["example.com"], args = [{host, string}], result = {res, rescode}}, #ejabberd_commands{name = convert_to_scram, tags = [sql], desc = "Convert the passwords in 'users' ODBC table to SCRAM", module = ejabberd_auth_sql, function = convert_to_scram, + args_desc = ["Vhost which users' passwords will be scrammed"], + args_example = ["example.com"], args = [{host, binary}], result = {res, rescode}}, #ejabberd_commands{name = import_prosody, tags = [mnesia, sql, riak], desc = "Import data from Prosody", module = prosody2ejabberd, function = from_dir, + args_desc = ["Full path to the Prosody data directory"], + args_example = ["/var/lib/prosody/datadump/"], args = [{dir, string}], result = {res, rescode}}, #ejabberd_commands{name = convert_to_yaml, tags = [config], desc = "Convert the input file from Erlang to YAML format", module = ejabberd_config, function = convert_to_yaml, + args_desc = ["Full path to the original configuration file", "And full path to final file"], + args_example = ["/etc/ejabberd/ejabberd.cfg", "/etc/ejabberd/ejabberd.yml"], args = [{in, string}, {out, string}], result = {res, rescode}}, @@ -222,11 +271,15 @@ get_commands_spec() -> #ejabberd_commands{name = delete_old_messages, tags = [purge], desc = "Delete offline messages older than DAYS", module = ?MODULE, function = delete_old_messages, + args_desc = ["Number of days"], + args_example = [31], args = [{days, integer}], result = {res, rescode}}, #ejabberd_commands{name = export2sql, tags = [mnesia], - desc = "Export virtual host information from Mnesia tables to SQL files", + desc = "Export virtual host information from Mnesia tables to SQL file", module = ejd2sql, function = export, + args_desc = ["Vhost", "Full path to the destination SQL file"], + args_example = ["example.com", "/var/lib/ejabberd/example.com.sql"], args = [{host, string}, {file, string}], result = {res, rescode}}, #ejabberd_commands{name = set_master, tags = [mnesia], @@ -234,36 +287,54 @@ get_commands_spec() -> longdesc = "If you provide as nodename \"self\", this " "node will be set as its own master.", module = ?MODULE, function = set_master, + args_desc = ["Name of the erlang node that will be considered master of this node"], + args_example = ["ejabberd@machine7"], args = [{nodename, string}], result = {res, restuple}}, #ejabberd_commands{name = mnesia_change_nodename, tags = [mnesia], desc = "Change the erlang node name in a backup file", module = ?MODULE, function = mnesia_change_nodename, + args_desc = ["Name of the old erlang node", "Name of the new node", + "Path to old backup file", "Path to the new backup file"], + args_example = ["ejabberd@machine1", "ejabberd@machine2", + "/var/lib/ejabberd/old.backup", "/var/lib/ejabberd/new.backup"], args = [{oldnodename, string}, {newnodename, string}, {oldbackup, string}, {newbackup, string}], result = {res, restuple}}, #ejabberd_commands{name = backup, tags = [mnesia], desc = "Store the database to backup file", module = ?MODULE, function = backup_mnesia, + args_desc = ["Full path for the destination backup file"], + args_example = ["/var/lib/ejabberd/database.backup"], args = [{file, string}], result = {res, restuple}}, #ejabberd_commands{name = restore, tags = [mnesia], desc = "Restore the database from backup file", module = ?MODULE, function = restore_mnesia, + args_desc = ["Full path to the backup file"], + args_example = ["/var/lib/ejabberd/database.backup"], args = [{file, string}], result = {res, restuple}}, #ejabberd_commands{name = dump, tags = [mnesia], - desc = "Dump the database to text file", + desc = "Dump the database to a text file", module = ?MODULE, function = dump_mnesia, + args_desc = ["Full path for the text file"], + args_example = ["/var/lib/ejabberd/database.txt"], args = [{file, string}], result = {res, restuple}}, #ejabberd_commands{name = dump_table, tags = [mnesia], - desc = "Dump a table to text file", + desc = "Dump a table to a text file", module = ?MODULE, function = dump_table, + args_desc = ["Full path for the text file", "Table name"], + args_example = ["/var/lib/ejabberd/table-muc-registered.txt", "muc_registered"], args = [{file, string}, {table, string}], result = {res, restuple}}, #ejabberd_commands{name = load, tags = [mnesia], - desc = "Restore the database from text file", + desc = "Restore the database from a text file", module = ?MODULE, function = load_mnesia, + args_desc = ["Full path to the text file"], + args_example = ["/var/lib/ejabberd/database.txt"], args = [{file, string}], result = {res, restuple}}, #ejabberd_commands{name = install_fallback, tags = [mnesia], desc = "Install the database from a fallback file", module = ?MODULE, function = install_fallback_mnesia, + args_desc = ["Full path to the fallback file"], + args_example = ["/var/lib/ejabberd/database.fallback"], args = [{file, string}], result = {res, restuple}} ]. -- 2.40.0