]> granicus.if.org Git - ejabberd/commitdiff
Describe even more command arguments and results in mod_admin_extra
authorBadlop <badlop@process-one.net>
Fri, 14 Jul 2017 14:43:22 +0000 (16:43 +0200)
committerBadlop <badlop@process-one.net>
Fri, 14 Jul 2017 14:43:30 +0000 (16:43 +0200)
src/mod_admin_extra.erl

index f2cb69273bcdf83bc36a6786ca956b174964fffa..42d2879fd34c501e5cc81ac4584e6645e0c23fd1 100644 (file)
@@ -303,6 +303,9 @@ get_commands_spec() ->
                        desc = "List of users logged in host with their statuses",
                        module = ?MODULE, function = status_list,
                        args = [{host, binary}, {status, binary}],
+                       args_example = [<<"myserver.com">>, <<"dnd">>],
+                       args_desc = ["Server name", "Status type to check"],
+                       result_example = [{<<"peter">>,<<"myserver.com">>,<<"tka">>,6,<<"Busy">>}],
                        result = {users, {list,
                                          {userstatus, {tuple, [
                                                                {user, string},
@@ -316,6 +319,9 @@ get_commands_spec() ->
                        desc = "List of logged users with this status",
                        module = ?MODULE, function = status_list,
                        args = [{status, binary}],
+                       args_example = [<<"dnd">>],
+                       args_desc = ["Status type to check"],
+                       result_example = [{<<"peter">>,<<"myserver.com">>,<<"tka">>,6,<<"Busy">>}],
                        result = {users, {list,
                                          {userstatus, {tuple, [
                                                                {user, string},
@@ -330,6 +336,8 @@ get_commands_spec() ->
                        desc = "List all established sessions and their information",
                        module = ?MODULE, function = connected_users_info,
                        args = [],
+                       result_example = [{"user1@myserver.com/tka", "c2s", "127.0.0.1",
+                                           40092, 8, "ejabberd@localhost", 28}],
                        result = {connected_users_info,
                                  {list,
                                   {sessions, {tuple,
@@ -346,6 +354,9 @@ get_commands_spec() ->
                        tags = [session],
                        desc = "Get the list of established sessions in a vhost",
                        module = ?MODULE, function = connected_users_vhost,
+                       args_example = [<<"myexample.com">>],
+                       args_desc = ["Server name"],
+                       result_example = [<<"user1@myserver.com/tka">>, <<"user2@localhost/tka">>],
                        args = [{host, binary}],
                        result = {connected_users_vhost, {list, {sessions, string}}}},
      #ejabberd_commands{name = user_sessions_info,
@@ -353,6 +364,10 @@ get_commands_spec() ->
                        desc = "Get information about all sessions of a user",
                        module = ?MODULE, function = user_sessions_info,
                        args = [{user, binary}, {host, binary}],
+                       args_example = [<<"peter">>, <<"myserver.com">>],
+                       args_desc = ["User name", "Server name"],
+                       result_example = [{"c2s", "127.0.0.1", 42656,8, "ejabberd@localhost",
+                                           231, <<"dnd">>, <<"tka">>, <<>>}],
                        result = {sessions_info,
                                  {list,
                                   {session, {tuple,
@@ -385,6 +400,9 @@ get_commands_spec() ->
                            "defined by the user client.",
                        module = ?MODULE, function = get_presence,
                        args = [{user, binary}, {server, binary}],
+                       args_example = [<<"peter">>, <<"myexample.com">>],
+                       args_desc = ["User name", "Server name"],
+                       result_example = {<<"user1@myserver.com/tka">>, <<"dnd">>, <<"Busy">>},
                        result =
                            {presence,
                             {tuple,
@@ -398,24 +416,40 @@ get_commands_spec() ->
                                {resource, binary}, {type, binary},
                                {show, binary}, {status, binary},
                                {priority, binary}],
+                       args_example = [<<"user1">>,<<"myserver.com">>,<<"tka1">>,
+                                       <<"available">>,<<"away">>,<<"BB">>, <<"7">>],
+                       args_desc = ["User name", "Server name", "Resource",
+                                       "Type: available, error, probe...",
+                                       "Show: away, chat, dnd, xa.", "Status text",
+                                       "Priority, provide this value as an integer"],
                        result = {res, rescode}},
 
      #ejabberd_commands{name = set_nickname, tags = [vcard],
                        desc = "Set nickname in a user's vCard",
                        module = ?MODULE, function = set_nickname,
                        args = [{user, binary}, {host, binary}, {nickname, binary}],
+                       args_example = [<<"user1">>,<<"myserver.com">>,<<"User 1">>],
+                       args_desc = ["User name", "Server name", "Nickname"],
                        result = {res, rescode}},
      #ejabberd_commands{name = get_vcard, tags = [vcard],
                        desc = "Get content from a vCard field",
                        longdesc = Vcard1FieldsString ++ "\n" ++ Vcard2FieldsString ++ "\n\n" ++ VcardXEP,
                        module = ?MODULE, function = get_vcard,
                        args = [{user, binary}, {host, binary}, {name, binary}],
+                       args_example = [<<"user1">>,<<"myserver.com">>,<<"NICKNAME">>],
+                       args_desc = ["User name", "Server name", "Field name"],
+                       result_example = "User 1",
+                       result_desc = "Field content",
                        result = {content, string}},
      #ejabberd_commands{name = get_vcard2, tags = [vcard],
-                       desc = "Get content from a vCard field",
+                       desc = "Get content from a vCard subfield",
                        longdesc = Vcard2FieldsString ++ "\n\n" ++ Vcard1FieldsString ++ "\n" ++ VcardXEP,
                        module = ?MODULE, function = get_vcard,
                        args = [{user, binary}, {host, binary}, {name, binary}, {subname, binary}],
+                       args_example = [<<"user1">>,<<"myserver.com">>,<<"N">>, <<"FAMILY">>],
+                       args_desc = ["User name", "Server name", "Field name", "Subfield name"],
+                       result_example = "Schubert",
+                       result_desc = "Field content",
                        result = {content, string}},
      #ejabberd_commands{name = get_vcard2_multi, tags = [vcard],
                        desc = "Get multiple contents from a vCard field",
@@ -429,12 +463,16 @@ get_commands_spec() ->
                        longdesc = Vcard1FieldsString ++ "\n" ++ Vcard2FieldsString ++ "\n\n" ++ VcardXEP,
                        module = ?MODULE, function = set_vcard,
                        args = [{user, binary}, {host, binary}, {name, binary}, {content, binary}],
+                       args_example = [<<"user1">>,<<"myserver.com">>, <<"URL">>, <<"www.example.com">>],
+                       args_desc = ["User name", "Server name", "Field name", "Value"],
                        result = {res, rescode}},
      #ejabberd_commands{name = set_vcard2, tags = [vcard],
                        desc = "Set content in a vCard subfield",
                        longdesc = Vcard2FieldsString ++ "\n\n" ++ Vcard1FieldsString ++ "\n" ++ VcardXEP,
                        module = ?MODULE, function = set_vcard,
                        args = [{user, binary}, {host, binary}, {name, binary}, {subname, binary}, {content, binary}],
+                       args_example = [<<"user1">>,<<"myserver.com">>,<<"TEL">>, <<"NUMBER">>, <<"123456">>],
+                       args_desc = ["User name", "Server name", "Field name", "Subfield name", "Value"],
                        result = {res, rescode}},
      #ejabberd_commands{name = set_vcard2_multi, tags = [vcard],
                        desc = "Set multiple contents in a vCard subfield",
@@ -451,6 +489,10 @@ get_commands_spec() ->
                                {user, binary}, {server, binary},
                                {nick, binary}, {group, binary},
                                {subs, binary}],
+                       args_example = [<<"user1">>,<<"myserver.com">>,<<"user2">>, <<"myserver.com">>,
+                               <<"User 2">>, <<"Friends">>, <<"both">>],
+                       args_desc = ["User name", "Server name", "Contact user name", "Contact server name",
+                               "Nickname", "Group", "Subscription"],
                        result = {res, rescode}},
      %%{"", "subs= none, from, to or both"},
      %%{"", "example: add-roster peter localhost mike server.com MiKe Employees both"},
@@ -460,6 +502,8 @@ get_commands_spec() ->
                        module = ?MODULE, function = delete_rosteritem,
                        args = [{localuser, binary}, {localserver, binary},
                                {user, binary}, {server, binary}],
+                       args_example = [<<"user1">>,<<"myserver.com">>,<<"user2">>, <<"myserver.com">>],
+                       args_desc = ["User name", "Server name", "Contact user name", "Contact server name"],
                        result = {res, rescode}},
      #ejabberd_commands{name = process_rosteritems, tags = [roster],
                        desc = "List/delete rosteritems that match filter (only Mnesia)",
@@ -514,8 +558,14 @@ get_commands_spec() ->
                                                                     ]}}}}},
      #ejabberd_commands{name = push_roster, tags = [roster],
                        desc = "Push template roster from file to a user",
+                       longdesc = "The text file must contain an erlang term: a list "
+                           "of tuples with username, servername, group and nick. Example:\n"
+                           "[{\"user1\", \"localhost\", \"Workers\", \"User 1\"},\n"
+                           " {\"user2\", \"localhost\", \"Workers\", \"User 2\"}].",
                        module = ?MODULE, function = push_roster,
                        args = [{file, binary}, {user, binary}, {host, binary}],
+                       args_example = [<<"/home/ejabberd/roster.txt">>, <<"user1">>, <<"localhost">>],
+                       args_desc = ["File path", "User name", "Server name"],
                        result = {res, rescode}},
      #ejabberd_commands{name = push_roster_all, tags = [roster],
                        desc = "Push template roster from file to all those users",
@@ -525,11 +575,15 @@ get_commands_spec() ->
                            " {\"user2\", \"localhost\", \"Workers\", \"User 2\"}].",
                        module = ?MODULE, function = push_roster_all,
                        args = [{file, binary}],
+                       args_example = [<<"/home/ejabberd/roster.txt">>],
+                       args_desc = ["File path"],
                        result = {res, rescode}},
      #ejabberd_commands{name = push_alltoall, tags = [roster],
                        desc = "Add all the users to all the users of Host in Group",
                        module = ?MODULE, function = push_alltoall,
                        args = [{host, binary}, {group, binary}],
+                       args_example = [<<"myserver.com">>,<<"Everybody">>],
+                       args_desc = ["Server name", "Group name"],
                        result = {res, rescode}},
 
      #ejabberd_commands{name = get_last, tags = [last],
@@ -538,6 +592,10 @@ get_commands_spec() ->
                            "2017-02-23T22:25:28.063062Z     ONLINE",
                        module = ?MODULE, function = get_last,
                        args = [{user, binary}, {host, binary}],
+                       args_example = [<<"user1">>,<<"myserver.com">>],
+                       args_desc = ["User name", "Server name"],
+                       result_example = {<<"2017-06-30T14:32:16.060684Z">>, "ONLINE"},
+                       result_desc = "Last activity timestamp and status",
                        result = {last_activity,
                                  {tuple, [{timestamp, string},
                                           {status, string}
@@ -548,17 +606,24 @@ get_commands_spec() ->
                        "1970-01-01 00:00:00 UTC, for example: date +%s",
                        module = mod_last, function = store_last_info,
                        args = [{user, binary}, {host, binary}, {timestamp, integer}, {status, binary}],
+                       args_example = [<<"user1">>,<<"myserver.com">>, <<"2017-06-30T14:32:16.060684Z">>, <<"GoSleeping">>],
+                       args_desc = ["User name", "Server name"],
                        result = {res, rescode}},
 
      #ejabberd_commands{name = private_get, tags = [private],
                        desc = "Get some information from a user private storage",
                        module = ?MODULE, function = private_get,
                        args = [{user, binary}, {host, binary}, {element, binary}, {ns, binary}],
+                       args_example = [<<"user1">>,<<"myserver.com">>,<<"storage">>, <<"storage:rosternotes">>],
+                       args_desc = ["User name", "Server name", "Element name", "Namespace"],
                        result = {res, string}},
      #ejabberd_commands{name = private_set, tags = [private],
                        desc = "Set to the user private storage",
                        module = ?MODULE, function = private_set,
                        args = [{user, binary}, {host, binary}, {element, binary}],
+                       args_example = [<<"user1">>,<<"myserver.com">>,
+                            <<"<query xmlns='jabber:iq:private'> <storage xmlns='storage:rosternotes'/></query>">>],
+                       args_desc = ["User name", "Server name", "XML storage element"],
                        result = {res, rescode}},
 
      #ejabberd_commands{name = srg_create, tags = [shared_roster_group],
@@ -568,41 +633,63 @@ get_commands_spec() ->
                        "put  \\ \" around the argument and\nseparate the "
                        "identifiers with \\ \\ n\n"
                        "For example:\n"
-                       "  ejabberdctl srg_create group3 localhost "
+                       "  ejabberdctl srg_create group3 myserver.com "
                        "name desc \\\"group1\\\\ngroup2\\\"",
                        module = ?MODULE, function = srg_create,
                        args = [{group, binary}, {host, binary},
                                {name, binary}, {description, binary}, {display, binary}],
+                       args_example = [<<"group3">>, <<"myserver.com">>, <<"Group3">>,
+                               <<"Third group">>, <<"group1\\\\ngroup2">>],
+                       args_desc = ["Group identifier", "Group server name", "Group name",
+                               "Group description", "Groups to display"],
                        result = {res, rescode}},
      #ejabberd_commands{name = srg_delete, tags = [shared_roster_group],
                        desc = "Delete a Shared Roster Group",
                        module = ?MODULE, function = srg_delete,
                        args = [{group, binary}, {host, binary}],
+                       args_example = [<<"group3">>, <<"myserver.com">>],
+                       args_desc = ["Group identifier", "Group server name"],
                        result = {res, rescode}},
      #ejabberd_commands{name = srg_list, tags = [shared_roster_group],
                        desc = "List the Shared Roster Groups in Host",
                        module = ?MODULE, function = srg_list,
                        args = [{host, binary}],
+                       args_example = [<<"myserver.com">>],
+                       args_desc = ["Server name"],
+                       result_example = [<<"group1">>, <<"group2">>],
+                       result_desc = "List of group identifiers",
                        result = {groups, {list, {id, string}}}},
      #ejabberd_commands{name = srg_get_info, tags = [shared_roster_group],
                        desc = "Get info of a Shared Roster Group",
                        module = ?MODULE, function = srg_get_info,
                        args = [{group, binary}, {host, binary}],
+                       args_example = [<<"group3">>, <<"myserver.com">>],
+                       args_desc = ["Group identifier", "Group server name"],
+                       result_example = [{<<"name">>, "Group 3"}, {<<"displayed_groups">>, "group1"}],
+                       result_desc = "List of group informations, as key and value",
                        result = {informations, {list, {information, {tuple, [{key, string}, {value, string}]}}}}},
      #ejabberd_commands{name = srg_get_members, tags = [shared_roster_group],
                        desc = "Get members of a Shared Roster Group",
                        module = ?MODULE, function = srg_get_members,
                        args = [{group, binary}, {host, binary}],
+                       args_example = [<<"group3">>, <<"myserver.com">>],
+                       args_desc = ["Group identifier", "Group server name"],
+                       result_example = [<<"user1@localhost">>, <<"user2@localhost">>],
+                       result_desc = "List of group identifiers",
                        result = {members, {list, {member, string}}}},
      #ejabberd_commands{name = srg_user_add, tags = [shared_roster_group],
                        desc = "Add the JID user@host to the Shared Roster Group",
                        module = ?MODULE, function = srg_user_add,
                        args = [{user, binary}, {host, binary}, {group, binary}, {grouphost, binary}],
+                       args_example = [<<"user1">>, <<"myserver.com">>, <<"group3">>, <<"myserver.com">>],
+                       args_desc = ["Username", "User server name", "Group identifier", "Group server name"],
                        result = {res, rescode}},
      #ejabberd_commands{name = srg_user_del, tags = [shared_roster_group],
                        desc = "Delete this JID user@host from the Shared Roster Group",
                        module = ?MODULE, function = srg_user_del,
                        args = [{user, binary}, {host, binary}, {group, binary}, {grouphost, binary}],
+                       args_example = [<<"user1">>, <<"myserver.com">>, <<"group3">>, <<"myserver.com">>],
+                       args_desc = ["Username", "User server name", "Group identifier", "Group server name"],
                        result = {res, rescode}},
 
      #ejabberd_commands{name = get_offline_count,
@@ -611,27 +698,42 @@ get_commands_spec() ->
                        policy = user,
                        module = mod_offline, function = count_offline_messages,
                        args = [],
+                       result_example = 5,
+                       result_desc = "Number",
                        result = {value, integer}},
      #ejabberd_commands{name = send_message, tags = [stanza],
                        desc = "Send a message to a local or remote bare of full JID",
                        module = ?MODULE, function = send_message,
                        args = [{type, binary}, {from, binary}, {to, binary},
                                {subject, binary}, {body, binary}],
+                       args_example = [<<"headline">>, <<"admin@localhost">>, <<"user1@localhost">>,
+                               <<"Restart">>, <<"In 5 minutes">>],
+                       args_desc = ["Message type: normal, chat, headline", "User server name",
+                               "Sender JID", "Destination JID", "Subject, or empty string", "Body"],
                        result = {res, rescode}},
      #ejabberd_commands{name = send_stanza_c2s, tags = [stanza],
                        desc = "Send a stanza as if sent from a c2s session",
                        module = ?MODULE, function = send_stanza_c2s,
                        args = [{user, binary}, {host, binary}, {resource, binary}, {stanza, binary}],
+                       args_example = [<<"admin">>, <<"myserver.com">>, <<"bot">>,
+                               <<"<message to='user1@localhost'><ext attr='value'/></message>">>],
+                       args_desc = ["Username", "Server name", "Resource", "Stanza"],
                        result = {res, rescode}},
      #ejabberd_commands{name = send_stanza, tags = [stanza],
                        desc = "Send a stanza; provide From JID and valid To JID",
                        module = ?MODULE, function = send_stanza,
                        args = [{from, binary}, {to, binary}, {stanza, binary}],
+                       args_example = [<<"admin@localhost">>, <<"user1@localhost">>,
+                               <<"<message><ext attr='value'/></message>">>],
+                       args_desc = ["Sender JID", "Destination JID", "Stanza"],
                        result = {res, rescode}},
      #ejabberd_commands{name = privacy_set, tags = [stanza],
                        desc = "Send a IQ set privacy stanza for a local account",
                        module = ?MODULE, function = privacy_set,
                        args = [{user, binary}, {host, binary}, {xmlquery, binary}],
+                       args_example = [<<"user1">>, <<"myserver.com">>,
+                               <<"<query xmlns='jabber:iq:privacy'>...">>],
+                       args_desc = ["Username", "Server name", "Query XML element"],
                        result = {res, rescode}},
 
      #ejabberd_commands{name = stats, tags = [stats],
@@ -639,12 +741,20 @@ get_commands_spec() ->
                        policy = admin,
                        module = ?MODULE, function = stats,
                        args = [{name, binary}],
+                       args_example = [<<"registeredusers">>],
+                       args_desc = ["Statistic name"],
+                       result_example = 6,
+                       result_desc = "Integer statistic value",
                        result = {stat, integer}},
      #ejabberd_commands{name = stats_host, tags = [stats],
                        desc = "Get statistical value for this host: registeredusers onlineusers",
                        policy = admin,
                        module = ?MODULE, function = stats,
                        args = [{name, binary}, {host, binary}],
+                       args_example = [<<"registeredusers">>, <<"example.com">>],
+                       args_desc = ["Statistic name"],
+                       result_example = 6,
+                       result_desc = "Integer statistic value",
                        result = {stat, integer}}
     ].
 
@@ -952,7 +1062,7 @@ connected_users_info() ->
 
 connected_users_vhost(Host) ->
     USRs = ejabberd_sm:get_vh_session_list(Host),
-    [ [U, $@, S, $/, R] || {U, S, R} <- USRs].
+    [ jid:encode(jid:make(USR)) || USR <- USRs].
 
 %% Code copied from ejabberd_sm.erl and customized
 dirty_get_sessions_list2() ->