zii/MRCI
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Initial commit for the MRCI project.

Browse Source
This commit is contained in:
Maurice O'Neal 2019-09-06 23:43:07 -04:00
commit beb59ec2ab
165 changed files with 19959 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
.gitignore vendored Normal file
View File

@ -0,0 +1,49 @@
# C++ objects and libs
*.slo
*.lo
*.o
*.a
*.la
*.lai
*.so
*.dll
*.dylib
# Qt-es
object_script.*.Release
object_script.*.Debug
*_plugin_import.cpp
/.qmake.cache
/.qmake.stash
*.pro.user
*.pro.user.*
*.qbs.user
*.qbs.user.*
*.moc
moc_*.cpp
moc_*.h
qrc_*.cpp
ui_*.h
*.qmlc
*.jsc
Makefile*
*build-*
# Qt unit tests
target_wrapper.*
# QtCreator
*.autosave
# QtCreator Qml
*.qmlproject.user
*.qmlproject.user.*
# QtCreator CMake
CMakeLists.txt.user*
# QtCreator 4.8< compilation database
compile_commands.json
# QtCreator local machine specific files for imported projects
*creator.user*

101
MRCI.pro Normal file
View File

@ -0,0 +1,101 @@
#-------------------------------------------------
#
# Project created by QtCreator 2017-03-19
#
# This file is part of MRCI.
#
# MRCI is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# MRCI is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with MRCI under the LICENSE.md file. If not, see
# <http://www.gnu.org/licenses/>.
#
#-------------------------------------------------
QT -= gui
QT += network
QT += sql
CONFIG += console
CONFIG -= app_bundle
TARGET = mrci
win32 {
LIBS += -llibeay32 -lssleay32
} else {
LIBS += -lcrypto -lssl
}
SOURCES += src/main.cpp \
src/commands/channels.cpp \
src/commands/cmd_ranks.cpp \
src/commands/p2p.cpp \
src/session.cpp \
src/db.cpp \
src/make_cert.cpp \
src/int_loader.cpp \
src/tcp_server.cpp \
src/unix_signal.cpp \
src/cmd_executor.cpp \
src/common.cpp \
src/shell.cpp \
src/db_setup.cpp \
src/commands/users.cpp \
src/commands/mods.cpp \
src/commands/info.cpp \
src/commands/groups.cpp \
src/commands/cast.cpp \
src/commands/bans.cpp \
src/commands/admin.cpp \
src/commands/auth.cpp \
src/commands/command.cpp \
src/commands/cmd_state.cpp \
src/commands/acct_recovery.cpp \
src/commands/table_viewer.cpp \
src/commands/fs.cpp \
src/commands/certs.cpp
HEADERS += \
src/commands/channels.h \
src/commands/cmd_ranks.h \
src/commands/p2p.h \
src/session.h \
src/db.h \
src/make_cert.h \
src/int_loader.h \
src/tcp_server.h \
src/unix_signal.h \
src/cmd_executor.h \
src/common.h \
src/shell.h \
src/db_setup.h \
src/commands/users.h \
src/commands/mods.h \
src/commands/info.h \
src/commands/groups.h \
src/commands/cast.h \
src/commands/bans.h \
src/commands/admin.h \
src/commands/auth.h \
src/commands/command.h \
src/commands/cmd_state.h \
src/commands/acct_recovery.h \
src/commands/table_viewer.h \
src/commands/fs.h \
src/commands/certs.h
RESOURCES += \
cmd_docs.qrc

93
cmd_docs.qrc Normal file
View File

@ -0,0 +1,93 @@
<RCC>
<qresource prefix="/">
<file>docs/intern_commands/accept_ch.md</file>
<file>docs/intern_commands/add_acct.md</file>
<file>docs/intern_commands/add_ban.md</file>
<file>docs/intern_commands/add_cert.md</file>
<file>docs/intern_commands/add_ch.md</file>
<file>docs/intern_commands/add_group.md</file>
<file>docs/intern_commands/add_mod.md</file>
<file>docs/intern_commands/add_ranked_cmd.md</file>
<file>docs/intern_commands/add_rdonly_flag.md</file>
<file>docs/intern_commands/add_sub_ch.md</file>
<file>docs/intern_commands/auth.md</file>
<file>docs/intern_commands/cast.md</file>
<file>docs/intern_commands/cert_info.md</file>
<file>docs/intern_commands/close_host.md</file>
<file>docs/intern_commands/close_sub_ch.md</file>
<file>docs/intern_commands/cmd_info.md</file>
<file>docs/intern_commands/decline_ch.md</file>
<file>docs/intern_commands/find_ch.md</file>
<file>docs/intern_commands/force_set_email.md</file>
<file>docs/intern_commands/fs_cd.md</file>
<file>docs/intern_commands/fs_copy.md</file>
<file>docs/intern_commands/fs_delete.md</file>
<file>docs/intern_commands/fs_download.md</file>
<file>docs/intern_commands/fs_info.md</file>
<file>docs/intern_commands/fs_list.md</file>
<file>docs/intern_commands/fs_mkpath.md</file>
<file>docs/intern_commands/fs_move.md</file>
<file>docs/intern_commands/fs_upload.md</file>
<file>docs/intern_commands/host_config.md</file>
<file>docs/intern_commands/host_info.md</file>
<file>docs/intern_commands/invite_to_ch.md</file>
<file>docs/intern_commands/is_email_verified.md</file>
<file>docs/intern_commands/lock_acct.md</file>
<file>docs/intern_commands/ls_act_log.md</file>
<file>docs/intern_commands/ls_auth_log.md</file>
<file>docs/intern_commands/ls_bans.md</file>
<file>docs/intern_commands/ls_certs.md</file>
<file>docs/intern_commands/ls_ch_members.md</file>
<file>docs/intern_commands/ls_chs.md</file>
<file>docs/intern_commands/ls_cmds.md</file>
<file>docs/intern_commands/ls_dbg.md</file>
<file>docs/intern_commands/ls_groups.md</file>
<file>docs/intern_commands/ls_mods.md</file>
<file>docs/intern_commands/ls_open_chs.md</file>
<file>docs/intern_commands/ls_p2p.md</file>
<file>docs/intern_commands/ls_ranked_cmds.md</file>
<file>docs/intern_commands/ls_rdonly_flags.md</file>
<file>docs/intern_commands/ls_sub_chs.md</file>
<file>docs/intern_commands/ls_users.md</file>
<file>docs/intern_commands/my_info.md</file>
<file>docs/intern_commands/open_sub_ch.md</file>
<file>docs/intern_commands/p2p_close.md</file>
<file>docs/intern_commands/p2p_open.md</file>
<file>docs/intern_commands/p2p_request.md</file>
<file>docs/intern_commands/pause.md</file>
<file>docs/intern_commands/ping_peers.md</file>
<file>docs/intern_commands/preview_email.md</file>
<file>docs/intern_commands/recover_acct.md</file>
<file>docs/intern_commands/remove_ch_member.md</file>
<file>docs/intern_commands/rename_ch.md</file>
<file>docs/intern_commands/rename_sub_ch.md</file>
<file>docs/intern_commands/request_new_pw.md</file>
<file>docs/intern_commands/request_new_user_name.md</file>
<file>docs/intern_commands/request_pw_reset.md</file>
<file>docs/intern_commands/restart_host.md</file>
<file>docs/intern_commands/resume.md</file>
<file>docs/intern_commands/rm_acct.md</file>
<file>docs/intern_commands/rm_ban.md</file>
<file>docs/intern_commands/rm_cert.md</file>
<file>docs/intern_commands/rm_ch.md</file>
<file>docs/intern_commands/rm_mod.md</file>
<file>docs/intern_commands/rm_ranked_cmd.md</file>
<file>docs/intern_commands/rm_rdonly_flag.md</file>
<file>docs/intern_commands/rm_sub_ch.md</file>
<file>docs/intern_commands/set_active_flag.md</file>
<file>docs/intern_commands/set_disp_name.md</file>
<file>docs/intern_commands/set_email_template.md</file>
<file>docs/intern_commands/set_email.md</file>
<file>docs/intern_commands/set_group_rank.md</file>
<file>docs/intern_commands/set_group.md</file>
<file>docs/intern_commands/set_member_level.md</file>
<file>docs/intern_commands/set_pw.md</file>
<file>docs/intern_commands/set_sub_ch_level.md</file>
<file>docs/intern_commands/set_user_name.md</file>
<file>docs/intern_commands/term.md</file>
<file>docs/intern_commands/to_peer.md</file>
<file>docs/intern_commands/trans_group.md</file>
<file>docs/intern_commands/verify_email.md</file>
<file>docs/intern_commands/ch_owner_override.md</file>
</qresource>
</RCC>

184
docs/Async.md Normal file
View File

@ -0,0 +1,184 @@
### 6.1 Async Commands ###
An async command is a virtual command that the host can use to send data to the client at any time while connected to the host. As the name implies, the occurance of a client receiving data from an async command is not always the result of running a regular command in the current session. This can occur for example when information in your account is changed by another client connected to the host; your client would not know about this change until an async command is sent notify it of the change. These commands cannot be called directly by a client or even a module command object.
Async commands are not only used send data to the client but also used internally within the host to help session objects operating in different processes to communicate with each other. Some async commands in fact are considered internal only because the client should never see any data come from them at anytime.
These are considered "virtual" commands because there is no defined command objects attached to them. Instead, async commands are best identified by command id values 1-255. Here is a list of currently "defined" async commands:
```
#define ASYNC_RDY 1
#define ASYNC_SYS_MSG 2
#define ASYNC_EXE_CRASH 3
#define ASYNC_EXIT 4 // internal only
#define ASYNC_CAST 5 // internal only
#define ASYNC_MAXSES 6 // internal only
#define ASYNC_LOGOUT 7 // internal only
#define ASYNC_USER_DELETED 8 // internal only
#define ASYNC_GROUP_RENAMED 9 // internal only
#define ASYNC_DISP_RENAMED 10 // internal only
#define ASYNC_GRP_TRANS 11 // internal only
#define ASYNC_USER_GROUP_CHANGED 12 // internal only
#define ASYNC_CMD_RANKS_CHANGED 13 // internal only
#define ASYNC_RESTART 14 // internal only
#define ASYNC_ENABLE_MOD 15 // internal only
#define ASYNC_DISABLE_MOD 16 // internal only
#define ASYNC_GROUP_UPDATED 17 // internal only
#define ASYNC_END_SESSION 18 // internal only
#define ASYNC_USER_LOGIN 19 // internal only
#define ASYNC_RESTORE_AUTH 20 // internal only
#define ASYNC_TO_PEER 21
#define ASYNC_LIMITED_CAST 22
#define ASYNC_RW_MY_INFO 23 // internal only
#define ASYNC_P2P 24
#define ASYNC_CLOSE_P2P 25 // internal only
#define ASYNC_NEW_CH_MEMBER 26
#define ASYNC_DEL_CH 27
#define ASYNC_RENAME_CH 28
#define ASYNC_CH_ACT_FLAG 29
#define ASYNC_NEW_SUB_CH 30
#define ASYNC_RM_SUB_CH 31
#define ASYNC_RENAME_SUB_CH 32
#define ASYNC_INVITED_TO_CH 33
#define ASYNC_RM_CH_MEMBER 34
#define ASYNC_INVITE_ACCEPTED 35
#define ASYNC_MEM_LEVEL_CHANGED 36
#define ASYNC_SUB_CH_LEVEL_CHG 37
#define ASYNC_ADD_RDONLY 38
#define ASYNC_RM_RDONLY 39
#define ASYNC_ADD_CMD 40
#define ASYNC_RM_CMD 41
#define ASYNC_USER_RENAMED 42
#define ASYNC_PUBLIC_AUTH 43 // internal only
```
### 6.2 Async Data ###
```ASYNC_RDY (1)```
This command signals to the client that your current session is now ready to start running commands. This is usually sent after successfully setting up the tcp connection ([protocol](Protocol.md)) or after successfully recovering from a session crash. It can carry ```TEXT``` data that can be displayed directly to the user if needed.
```ASYNC_SYS_MSG (2)```
This command carry ```TEXT``` or ```ERR``` data that are system messages that can be directly displayed to the user of needed. It is also used to carry ```HOST_CERT``` data during the tcp connection setup and ```MY_INFO``` when local user account information has changed.
```ASYNC_EXE_CRASH (3)```
This is used to send ```ERR``` messages to the client if your session crashes or fails to setup an IPC connection for any reason.
```ASYNC_EXIT (4)```
This is an internal async command that doesn't carry any data. It is used to send a ```closeServer()``` signal to the ```TCPServer``` object in the main process. This will cause it stop listing for clients, close all sessions and then close the main process.
```ASYNC_CAST (5)```
This is an internal only command that carries a 54byte open sub-channels list ```wrAbleChIds``` described in section [3.4](Command_Objects.md) and an embedded mrci frame that can then be sent to clients that have any of the matching open sub-channels. It drops that sub-channel list before arriving at the client so it will apppear like a regular mrci frame of any data type.
```ASYNC_MAXSES (6)```
Internal only async command that is used by internal commands to send a ```BYTES``` frame to the main process to update the maximum amount the concurrent sessions for the ```TCPServer``` object. The data itself is actually a 32bit unsigned int.
```ASYNC_LOGOUT (7)```
This internal only async command doesn't carry any data. This is just used to notify the main process ```Session``` object that the user has logged out and should not attempt to restore authentication in case of a session crash. This doesn't actually do the logout.
```ASYNC_USER_DELETED (8)```
This internal only async command carry ```TEXT``` data that is the user name of the user account that was deleted from the host database. All ```Session``` objects that get this command must read and match this to the user name that is currently logged in for that object. If the user name matches, the ```Session``` object must logout since the user account no longer exists.
```ASYNC_GROUP_RENAMED (9)```
Internal only async command that carry ```TEXT``` command line arguments to notify all ```Session``` objects that the a host group name has changed. Example: ```-src "old_group_name" -dst "new_group_name"```. All ```Session``` objects that have matching current group names to ```old_group_name``` must update that group name to ```new_group_name``` and also send a ```ASYNC_SYS_MSG``` containing an updated ```MY_INFO```.
```ASYNC_DISP_RENAMED (10)```
Internal only async command that carry ```TEXT``` command line arguments to notify all ```Session``` objects that a user has changed the display name. Example: ```-name "new_display_name" -user "user_name"```. All ```Session``` objects that have matching current user names to ```user_name``` must update the display name to ```new_display_name``` and also send a ```ASYNC_SYS_MSG``` containing an updated ```MY_INFO```.
```ASYNC_GRP_TRANS (11)```
Internal only async command that carry the same ```TEXT``` command line arguments as ```ASYNC_GROUP_RENAMED``` to notify all ```Session``` objects that the all users currently in the group given in ```-src``` must be updated to the group given in ```-dst```. This triggers a ```ASYNC_SYS_MSG``` to send an updated ```MY_INFO``` and the ```Session``` object will load all the commands that the user now have access to and remove any commands that lost access due to the group change.
```ASYNC_USER_GROUP_CHANGED (12)```
This is an internal only command carry ```TEXT``` command line arguments to notify all ```Session``` objects that a user's group was changed to another group. example: ```-user "user_name" -group "new_group"```. All ```Session``` objects the have the matching user name need to update it's group to ```new_group```, send a ```ASYNC_SYS_MSG``` with an updated ```MY_INFO``` and load all the commands that the user now have access to and remove any commands that lost access due to the group change.
```ASYNC_CMD_RANKS_CHANGED (13)```
This internal only async commmand doesn't carry any data. Instead, it notifies all ```Session``` objects that assigned command ranks have changed. This will cause all of the ```Session``` objects to re-check the currently loaded commands and determine if it needs to remove any commands that the user no longer have access to and add any commands that the user may have gained access to.
```ASYNC_RESTART (14)```
This internal only async commmand doesn't carry any data. It is used to send a ```resServer()``` signal to the ```TCPServer``` object in the main process. This will cause it stop listing for clients, close all sessions, reload the host settings and start listening for clients again.
```ASYNC_ENABLE_MOD (15)```
This internal only async commmand carry ```TEXT``` path to the main library file of a module. All ```Session``` objects will then load the module.
```ASYNC_DISABLE_MOD (16)```
This internal only async commmand carry ```TEXT``` path to the main library file of a module. All ```Session``` objects will then delete all commands associated with the with this module and then unload it.
```ASYNC_GROUP_UPDATED (17)```
This is an internal only command that carry ```TEXT``` command line arguments to notify all ```Session``` objects that a group's host rank has changed. Example: ```-name "group_name" -rank 2```. All ```Session``` object that have matching group names to ```group_name``` will need to update the host rank to ```2```. When the session's host rank to adjusted this way, the session will need to re-check the currently loaded commands and determine if it needs to remove any commands that the user no longer have access to and add any commands that the user may have gained access to.
```ASYNC_END_SESSION (18)```
This internal only async commmand doesn't carry any data. It is used to notify the main process that the ```CmdExecutor``` object is requesting to close the session. The main process ```Session``` object will then signal the slave process to close and close the tcp session.
```ASYNC_USER_LOGIN (19)```
This is an internal only command that carry ```PRIV_IPC``` data containing the 256bit Keccak hash user id of the user that has successfully logged in. This is used by the ```CmdExecutor``` object to notify the main process ```Session``` object of the current user associated with the current session. The main process ```Session``` object will use this information to restore the user authorization in case of a session crash.
```ASYNC_RESTORE_AUTH (20)```
This is an internal only command that carry ```PRIV_IPC``` data containing the 256bit Keccak hash user id of a user that has successfully logged in with the current session. It is used by the ```Session``` object in the main process to tell the ```CmdExecutor``` object in the slave process to authorize the user without a password. This is only used when attempting to restore the session from a crash and a user was logged in at the time.
```ASYNC_TO_PEER (21)```
This is an async command that carry an embedded mrci frame directly to/from peer sessions without any restrictions. It is prepended with the 224bit sha3 hash of the target session id; however, it drops that session id before arriving at the client so it will apppear as a regular mrci frame of any data type. Users should not be given direct access to this for security reasons.
```ASYNC_LIMITED_CAST (22)```
This operate exactly like ```ASYNC_CAST``` except only sessions with active update sub-channels will respond to it.
```ASYNC_RW_MY_INFO (23)```
This internal only async command carry ```TEXT``` data of the user name to tell all ```Session``` objects that have the matching user name to send an update ```MY_INFO``` to the client. This is useful for when a host admin force updates user information of other lesser privileged users to make their clients aware of the changes.
```ASYNC_P2P (24)```
This async command carry an embedded mrci frame directly to/from peer sessions following the p2p negotiation process as described in [Type_IDs](Type_IDs.md), section 4.2 at the P2P specific data types. It prepends the 224bit sha3 hash of the destination session id and source session id; however, it drops the destination id and source id for just the P2P specific data types before arriving at the client. For all other data types (if a p2p connection is estabished), the source id is prepend-moved to the payload of the mrci frame before arriving at the client.
```ASYNC_CLOSE_P2P (25)```
This internal only async command carry a 224bit sha3 hash session id of a session that is about to close. This notifies all ```CmdExecutor``` objects that have matching hashes in ```p2pAccepted``` and ```p2pPending``` (section [3.4](Command_Objects.md)) to remove them now. It also triggers a ```ASYNC_P2P``` to send a ```P2P_CLOSE``` for the session id in question so the clients can also be made aware of this.
```ASYNC_NEW_CH_MEMBER (26)```
```TEXT``` command line arguments when a new channel is created and the user that created it is added as the channel owner. Example: ```-user "user_name" -ch_name "new_channel" -ch_id 334 -level 1```.
```ASYNC_DEL_CH (27)```
```TEXT``` command line arguments when a channel is deleted. Example: ```-ch_name "channel_name" -ch_id 426```. The host will automatically close all sub-channels related to this channel for all sessions that have them open.
```ASYNC_RENAME_CH (28)```
```TEXT``` command line arguments when a channel is renamed. Example: ```-ch_name "old_name" -new_name "new_name"```.
```ASYNC_CH_ACT_FLAG (29)```
```TEXT``` command line arguments when sub-channel's active update flag has been updated. Example: ```-ch_name "channel_name" -sub_name "sub_channel" -state 1```. (```-state``` 1 is true or ```-state``` 0 is false).
```ASYNC_NEW_SUB_CH (30)```
```TEXT``` command line arguments when a new sub-channel is created. Example: ```-ch_name "channel_name" -sub_name "new_sub_channel" -ch_id 987 -sub_id 5 -level 2```.
```ASYNC_RM_SUB_CH (31)```
```TEXT``` command line arguments when a sub-channel is deleted. Example: ```-ch_name "channel_name" -sub_name "sub_channel" -ch_id 987 -sub_id 5```. The host will automatically close this sub-channel for sessions that currently have it open.
```ASYNC_RENAME_SUB_CH (32)```
```TEXT``` command line arguments when a sub-channel is renamed. Example: ```-ch_name "channel_name" -sub_name "sub_channel" -new_name "new_sub_name"```.
```ASYNC_INVITED_TO_CH (33)```
```TEXT``` command line arguments when a new user is invited to join a channel. Example: ```-ch_name "channel_name" -user "user_name"```.
```ASYNC_RM_CH_MEMBER (34)```
```TEXT``` command line arguments when a user is kicked from a channel, uninvited or has left the channel. Example: ```-ch_name "channel_name" -user "user_name" -ch_id 746```.
```ASYNC_INVITE_ACCEPTED (35)```
```TEXT``` command line arguments when a user that was previously invite to join the channel has accepted the invite and should now be considered full member of the channel starting off at level ```REGULAR```. Example: ```-ch_name "channel_name" -user "user_name"```.
```ASYNC_MEM_LEVEL_CHANGED (36)```
```TEXT``` command line arguments when a channel member's privilege level is changed. Example: ```-ch_name "channel_name" -user "user_name" -ch_id 774 -level 2```. The host automatically closes all sub-channels related to the channel for the affected user. It will be will up to the client to re-open the sub-channel(s) if the user still have access to it/them.
```ASYNC_SUB_CH_LEVEL_CHG (37)```
```TEXT``` command line arguments when a sub-channel's lowest level of access is changed. Example: ```-ch_name "channel_name" -sub_name "sub_channel" -level 3 -ch_id 645 -sub_id 5```. The host will automatically close this sub-channel for sessions that currently have it open. It will be up to the client to reopen it if the current user still have access to it.
```ASYNC_ADD_RDONLY (38)```
```TEXT``` command line arguments when a read only flag is added to a sub-channel's access level. Example: ```-ch_name "channel_name" -sub_id 5 -level 4```. The host will automatically close this sub-channel for sessions that currently have it open. It will be up to the client to reopen it if the current user still have access to it.
```ASYNC_RM_RDONLY (39)```
```TEXT``` command line arguments when a read only flag is removed from a sub-channel's access level. Example: ```-ch_name "channel_name" -sub_id 5 -level 4```. The host will automatically close this sub-channel for sessions that currently have it open. It will be up to the client to reopen it if the current user still have access to it.
```ASYNC_ADD_CMD (40)```
This async command carry ```NEW_CMD``` when the session's ```CmdExecutor``` loads a new command object and wants to notify the client of it.
```ASYNC_RM_CMD (41)```
This async command carry ```CMD_ID``` when the session's ```CmdExecutor``` deletes a command object and wants to notify the client of it.
```ASYNC_USER_RENAMED (42)```
```TEXT``` command line arguments when a user changes it's user name. Example: ```-old "old_user_name" -new_name "new_user_name"```.
```ASYNC_PUBLIC_AUTH (43)```
This internal only async commmand doesn't carry any data. It just tells the ```CmdExecutor``` to load or reload commands without an authorized user so only public commands will be available until the client authorizes into a user account. This is used by the host when starting a session for the first time or if restoring the session after a crash and no user was logged in at the time.

57
docs/Command_Loaders.md Normal file
View File

@ -0,0 +1,57 @@
### 2.1 Command Loaders ###
Every command object ([Command_Objects](Command_Objects.md)) defined in the host must internally define a unique command name. Command loaders have the very simple job of creating these objects via the requested command name. The host use command names to determine if the current session is allowed to load them or not and command loaders are used to relate those command names with the command objects themselves.
When the host ```CmdExecutor``` determines that it can indeed load the commands based on the command names, it will then assign command ids to all command objects that were successfully built from the command loader. Each command loader can have a total of 256 command objects and internally defined commands start at command id: 256 - 512 and module defined commands start at command id: 513 and up.
### 2.2 CommandLoader Class ###
The ```CommandLoader``` class itself defines a few virtual functions that make the command name to command object relationship possible:
```ExternCommand *cmdObj(QString cmdName)```
This function is used to create the ```ExternCommand``` object associated with the command name passed by the ```QString``` parameter and return a pointer to it. If the command name is invalid, doesn't exists or fails to contruct the object for some reason, return ```nullptr```. The command object can have a parent or orphaned, just make sure it never gets deleted at any time; the host will handle that externally. It is safe to use the command loader itself as the parent.
```QStringList cmdList()```
This function needs to return a ```QStringList``` of all of command names that this loader can actually load when the ```cmdObj()``` function is called. the host uses this list to enforce user access filtering of the command objects using the built in permission id system.
```QStringList pubCmdList()```
This funtion needs to work the same way as ```cmdList()``` except the loader will use this function to name any commands that can be accessed by un-logged in clients. aka, public commands. Note: the commands listed here must also be listed in ```cmdList()``` or else the commands will not get loaded at all.
```QStringList rankExemptList()```
The loader can use this function to return a ```QStringList``` of all of command names that need to be exempt from host ranking system (section [5.2](Host_Features.md)). Commands listed here will be allowed to load/run regardless of what host rank the current user is.
Here's a few notes to consider when using this class:
* Never self delete or explicitly delete the command loader or any of the command objects it sucessfully creates at any time. The host ```CmdExecutor``` object will handle the life cycle of these objects externally.
* Command ids are assigned in alphabetical order of the command names returned by ```cmdList()```. The command ids will remain constant as long as the command names also remain constant. All clients are recommended to rely on the ASYNC_ADD_CMD and ASYNC_RM_CMD async commands to keep track of the command ids and names (section [6.2](Async.md)).
### 2.3 Modules ###
External commands are added to the host through modules based on low level [QT plugins](https://doc.qt.io/qt-5/plugins-howto.html). Each module must define a ```ModCommandLoader``` class in it's main library file and the file itself must be named 'main' with a library file extension that the host platform supports (main.so, main.dll, etc..). Modules are installed using the *add_mod* internal command that supports extracting the module's library files from an archive file (.zip, .tar, etc...) or just a single library file (.so, .dll, .a, etc...).
In the case of an archive file, it extracts all of the files from the the archive file while preserving the directory tree so you can bundle additional files that your module depends on but as mentioned before, a library file named 'main' must be present on the base directory.
A template and an example of a module can be found in the 'modules/Tester' directory of the source code of this project. It provides the command.cpp and command.h files that contain the ```ModCommandLoader```, ```CommandLoader``` and ```ExternCommand``` classes that are needed to create a module. Also feel free to copy the command.cpp and command.h files from 'src/commands' if you prefer.
### 2.4 The Import Rev ###
The import rev is a single digit versioning system for external modules that help the host determine if it is compatible with the module it is attempting to load or not. Bumps to this rev is usually triggered by significant changes to the ```CommandLoader``` or ```ModCommandLoader``` classes. Compatibility negotiation is a two way communication between the host ```CmdExecutor``` and the module itself using the virtual functions described in section 2.5.
### 2.5 ModCommandLoader Class ###
This class uses ```CommandLoader``` as a base and adds more virtual functions more suitable for loading command objects from an external library file:
```bool hostRevOk(quint64 rev)```
When the host calls this function, it will pass the import rev that it supports in the ```quint64``` parameter. Use this function to return if this rev is acceptable or not. The host will give up loading the module if the rev is not acceptable.
```quint64 rev()```
Use this function to return the import rev that this module supports. The host will decide if it is acceptable or not.
```QString lastError()```
The host will call this function if a command object fails to load or if ```hostRevOk()``` returns false so it can log the error message returned by it to the host database.
```void modPath(QString path)```
The host will call this function after successfully negotiating the import rev. The ```QString``` parameter passed into this will have the absolute path to the module's install directory. You can use this path to load additional files that came bundled in the archive file.
```void aboutToDelete()```
The host will call this function before calling ```deleteLater()```. All command objects at this point should already be deleted, use this opportunity to free any resources related to the loader itself. Unload any additional lib files that the loader may have used.

193
docs/Command_Objects.md Normal file
View File

@ -0,0 +1,193 @@
### 3.1 Command Objects ###
```ExternCommand``` objects are QT/C++ classes used by the host to execute all logic related to the specific commands called by the client. It basically defines several QT signals and virtual functions that the host's internal ```CmdExecutor``` object uses to process input data from the client and return data to the client or to other peers connected to the host. Each command callable by the client defines a seperate ```ExternCommand``` object and it's life cycle is managed externally by the host's ```CmdExecutor``` object.
### 3.2 Defined Variables in ExternCommand ###
Aside from the virtual functions and QT signals, the ```ExternCommand``` object also defines a few public variables that can be of interest:
```cmdId```
This is a ```quint16``` command id that the command object was assigned to when it was built. Changing it at any time does nothing upstream but it is reset to it's proper value every time the ```procBin()``` function is called. the MRCI protocol use assigned command ids to call certain command objects currently loaded into the ```CmdExecutor``` object. It is unique to each command object and makes it possible for the client to call a command with only 2 bytes of data instead of a variable number of bytes for a command name. This variable exist to make it possible for the internal logic of the command object to be made aware of it's assigned command id.
```internCommands```
This is a ```QHash<QString, ExternCommand*>``` containing a list of pointers to internal command objects built to be used from within this command object. It is filled by the ```internRequest()``` function (section 3.3). Internal commands differ from external commands like this by having direct access to the host database and less restrictive access to various host functions. This variable is useful if you want access to such functions without the chance of causing a session crash or database corruption.
```errSent```
This is a ```bool``` that simply indicates if the command has sent error message to the client using the ```errTxt()``` non-virtual function. This is useful if you want to determine of the last run of the command was successful or not but only if the internal logic used the aforementioned function to send the error. The ```CmdExecutor``` does reset it to false before calling the ```procBin()``` function.
```inLoopMode```
This is a ```bool``` that indicates if the command object is currently in loop mode. This basically retains what was passed into the ```enableLoop()``` signal when it is called. more info on this can be found in section 3.5.
```inMoreInputMode```
This is a ```bool``` that indicates if the command object is currently in the more input state. It retains what was passed into the ```enableMoreInput()``` signal when it is called. see section 3.5 for more info.
```QString QObject::objectName()```
This is not a variable but it is a function available to the ```ExternCommand``` object from the QT API. The ```CmdExecutor``` assigns the unique command name to this property that was assigned to this command when it was built. Just like ```cmdId``` this makes the internal logic aware of it's assigned command name. Changing it using ```QObject::setObjectName()``` does nothing upstream but also unlike ```cmdId``` it is not reset upon calling ```procBin()```.
### 3.3 ExternCommand Virtual Functions ###
```void procBin(SharedObjs,QByteArray,uchar)```
This function is called by the host to process input data from the client passed in the form of a ```QByteArray```. Look at this as the main execution function of the command that can be called more than once if the loop state is enabled. The ```SharedObjs``` parameter is passed by the ```CmdExecutor``` to share information about the session with the command object as described in section 3.4 of this document. It is passed as a const because changing any of the objects within ```SharedObjs``` in an unexpected way may cause undesired behaviour. The third ```uchar``` parameter indicate what type of data is in the ```QByteArray```. Details on type ids can be found in the [Type_IDs.md](Type_IDs.md) document.
```bool handlesGenfile()```
Command objects should return true on this function if your command object handles the ```GEN_FILE``` data type in anyway. The host will use this to tell the client which commands support this data type which ones don't. The reason for this is because the ```GEN_FILE``` data type require structured 2 way communication in a way between the host and client (see [Type_IDs.md](Type_IDs.md)). This function is called only once shortly after the command is contructed.
```QString shortText()```
Command objects must return a short summary on what this command actually does. The host will use this to send help text to the client. How this text is displayed to the user depends entirely on the client.
```QString ioText()```
Just like shortText(), this is a help text function that describes what input/output data to expected to/from the command object. It follows a specific text format:
```
[] Brackets are used to indicate a block of data (text,binary,etc..).
Example: [text]
/ Seperates input and output data blocks to/from the command.
Example: [input_text]/[output_text]
- Indicates a argument.
Example: [-arg]/[text]
() Brackets indicate argument parameters/values.
Example: [-arg (text)]/[text]
{} Brackets indicate optional arguments or parameters.
Example: [-arg {(text)} {-optional}]/[text]
'or' Indicates optional input data blocks and/or possible output blocks.
Example: [-arg1 (text)] or [-arg2 (text)]/[output_text1] or [output_text2]
```
```QString longText()```
This is a help text function that is used by the host to send full detailed information about the command and it's usage. It's recommended to be as thorough as possible to help users understand proper usage of your command. The host will send it as ```BIG_TEXT``` so it will be up to the client if it should word-wrap the text when displaying to the user.
```QString libText()```
Command objects can use this function to return the library/module name and version that the command object belongs to. This can also contain extra information that clients can use to further identify the command object; however, the text is limited to 64 chars or less. Any text returned by this function that is larger than 64 chars will be truncated.
```QStringList internRequest()```
After the command is successfully built, this function is called by the ```CmdExecutor``` to fulfil any request to build internal command objects that can be used from within the object that was built. the ```QStringList``` returned by this function just need to list any of the known internal command names and the ```CmdExecutor``` will build them and add them to the ```internCommands``` ```QHash``` defined inside the ```ExternCommand``` object (section 3.2). Here's a few notes to consider if you want to build internal commands within your own command.
* Your command object is assigned the parent of the internal commands.
* The internal commands built into internCommands have full access to the internal host batabase and functions that normal ExternCommands would otherwise not have access to.
* The output from the internal commands go directly to the client, peers or other objects. Nothing is passed through the parent object by default.
* Clients do not have direct access to these specific internal commands. Instead, they can only be called by running the ```procBin()``` function directly from within the parent object.
* The internal commands inherit the parent command object's command id/name so output from these internal commands will appear as if it came from the parent object. This also includes the ```enableLoop()``` and ```enableMoreInput()``` signals (section 3.5).
* It will be up to the parent object to detect and execute the loop mode for these internal commands since ```CmdExecutor::exeCmd()``` will not call these objects directly.
* Terminating the parent object also terminates all of the internal commands within it.
* It is safe to delete the internals commands but be sure to remove the deleted commands from the ```internCommands``` ```QHash``` or it will must likely cause the session to crash. You normally should never have to do this anyway, the ```CmdExecutor``` will safely delete these internal commands when the parent is about to get deleted.
```void term()```
This function is called by the host when the command needs to terminate what it is currently doing. Use this opportunity to reset and clean up any reasources so the command object can be ready to be called again in a reset state.
```void aboutToDelete()```
The host will call this function before calling the command object's ```deleteLater()``` function. Use this opportunity to clean up anything the host may not be aware of in preparation for deletion. Avoid self deleting any ```ExternCommand``` object at any time, doing so will must certainly cause the session to crash.
```bool errState();```
Return true or false on this function to indicate if the command object is currently in an error state. The default logic simply returns ```errSent``` (section 3.2).
### 3.4 Shared Objects ###
The ```SharedObjs``` class is used by the host's ```Session``` and ```CmdExecutor``` objects to share data with all command objects. It contains pointers to various objects related to the user's current session and command states. It is passed into the command via the ```ExternCommand::procBin()``` function as a read only const. Below are all of the pointers defined within it:
```sessionId```
This is a ```QByteArray``` containing the 224bit (28byte) sha3 hash id unique to the current session only. this does change upon reconnecting to the host.
```p2pAccepted```
This is a ```QList<QByteArray>``` object that list all peer session ids that the user has accepted to be allowed to send/receive data when using the ```toPeer()``` signal.
```p2pPending```
This is a ```QList<QByteArray>``` object that list all peer session ids that sent a ```P2P_REQUEST``` to/from the session and are awaiting a ```P2P_OPEN```. When a ```P2P_OPEN``` is received, the session id sent by it is removed from this list and then added to ```p2pAccepted```.
```chIds```
This is a ```QByteArray``` object that string togeather up to 6 channel-sub combinations that indicate which channel id and sub id combinations are currently open. Each channel-sub are 9bytes long and chIds itself maintians a fixed length of 54bytes. It is padded with 0x00 chars to maintain the fixed length (this padding can appear anywhere in 9byte increments within chIds). Channel-sub is formatted like this:
```
bytes[0-7] - 64bit LE unsigned int (channel id)
bytes[8] - 8bit LE unsigned int (sub id)
note: channel id 0 is not a valid id and the sub id cannot
be valid without a valid channel id.
```
```wrAbleChIds```
This is a ```QByteArray``` object formatted exactly like ```chIds```. It however list all channel-subs from ```chIds``` that are 'writable.' This is what is actually used when casting data to peers while ```chIds``` is used when receiving data from peers. This cannot list any channel-subs that are not also listed in ```chIds```.
```chList```
This is a ```QList<QString>``` of channel names that the currently logged user is a member of. Unlike ```chIds```, this list doesn't care if the channel is open or not.
```activeUpdate```
This is a ```bool``` object that indicate if the above ```chIds``` contains an open active update channel. When a session is active updating it will respond to peer pings, ```PEER_INFO``` and ```PEER_STAT``` frames related to just the active update sub-channels.
```chOwnerOverride```
This is a ```bool``` object that indicates if the user currently have the channel owner override flag active or not. The owner override flag allows the user to do anything a channel owner could do in a channel without actually being the owner of the channel. This is usually reserved for host administrators.
```sessionAddr```
This is a ```QString``` representation of the IPv4 or IPv6 address of the TCP client.
```userName```
This is a ```QString``` of the current user that is logged in on the current session. This is empty if no user is currently logged in.
```groupName```
This is a ```QString``` of the group that the above ```userName``` is a member of. it is also blank if no user is currently logged in.
```displayName```
This is a ```QString``` of the user's desired display name. Clients are encouraged put more emphasis on this if displaying the user to the public.
```appName```
This is a ```QString``` of the client's application name. It can also contain the application's version depending on the application itself. This is updated upon connecting to the host and normally does not change while the session is active.
```clientMajor```
This is a ```ushort``` version major of the mrci protocol that the client is using.
```clientMinor```
This is a ```ushort``` version minor of the mrci protocol that the client is using.
```clientPatch```
This is a ```ushort``` version patch of the mrci protocol that the client is using.
```userId```
This is a ```QByteArray``` containing the 256bit (32byte) Keccak hash unique to the current user. This is empty if no user is currently logged in. This remains constant even when the user name, or any other user information changes.
```moreInputCmds```
This is a ```QList<quint16>``` of command ids that are currently in the more input state. Command objects in this state are simply requesting more input data from the client and should not be considered finished.
```activeLoopCmds```
This is a ```QList<quint16>``` of command ids that are currently in the loop state. Command objects in this state will cause the ```CmdExecutor``` to call ```ExternCommand::procBin()``` in a loop until it is removed from this list.
```pausedCmds```
This is a ```QList<quint16>``` containing a list of command ids that are blocked from looping. The commands listed here must also be listed in activeLoopCmds.
```hostRank```
This is a ```uint``` that indicates the currently logged in user's host rank. The host rank determines the level of access to the host commands the user currently have. what those commands could be depends on how the host is configured. The lower the rank value, the higher the privilege level with 1 being the highest level. 0 is not considered a valid rank and it will initialized as that if no user is currently logged in.
```cmdNames```
This is a ```QHash<quint16,QString>``` with command id ```quint16``` keys that relate to ```QString``` command names that are currently loaded for the session.
### 3.5 ExternCommand Signals ###
```dataToClient(QByteArray data, uchar typeId)```
This signal sends the data to ```CmdExecutor``` passed as a ```QByteArray``` with a ```uchar``` indicating what [TypeID](Type_IDs.md) is stored in that ```QByteArray```. The ```CmdExecutor``` object inspects the type id and stops external commands from sending the following data types: ```PRIV_IPC```, ```PUB_IPC```, ```NEW_CMD```, ```PEER_STAT```, ```MY_INFO```, ```PEER_INFO```, ```HOST_CERT```, ```IDLE```, ```PING_PEERS```, ```P2P_REQUEST```, ```P2P_OPEN```, ```P2P_CLOSE```. If none of these type ids are caught, the data is then sent to the client as a mrci frame.
```castToPeers(QByteArray data, uchar typeId)```
This is used to broadcast data to all clients that have any matching sub-channels open. It takes the same parameters and have the same retrictions as ```dataToClient()```.
```toPeer(QByteArray sessionId, QByteArray data, uchar typeId)```
This signal is used to send data directly to a peer client without the need to open any sub-channels. Instead, the data is routed via the target peer's session id, given in the 1st ```QByteArray``` parameter as 224bit (28byte) sha3 hash. The next 2 parameters are the same as ```dataToClient()```, however only the following data types are allowed until a connection is negotiated with the peer: ```P2P_REQUEST```, ```P2P_OPEN``` or ```P2P_CLOSE```. More info on this can be found in [Type_IDs.md](Type_IDs.md), section 4.2. Except the P2P specific data types, the same retrictions for ```dataToClient()``` also apply here.
```closeChById(quint64 channelId, uchar subId), closeChByName(QString channelName, QString subName), openChById(quint64 channelId, uchar subId), openChByName(QString channelName, QString subName)```
These signals open/close sub-channels via the channel and sub-channel names or ids. The ```CmdExecutor``` does error checking on these so errors are returned to the client if the channel or sub-channel does not exists, is invalid or if the user doesn't have access to it.
```enableLoop(bool state)```
This takes a ```bool``` value that enables or disables the command object's loop state. If the loop state is enabled, the ```procBin()``` function will be called by the ```CmdExecutor``` within it's own loop until the loop state is disabled. 3rd party module devs are highly recommended to use this rather than implementing their own long term loops. By letting the ```CmdExecutor``` handle the looping structure it would be possible for it terminate/interrupt the command more gracefully from the outside.
```enableMoreInput(bool state)```
This takes a ```bool``` value that enables or disables the command object's more input state. This state tells the ```CmdExecutor``` that the command is requesting more data from the client and should hold off sending an ```IDLE``` frame to the client because the command is not yet finished. if both loop and more input states are disabled, an ```IDLE``` frame is sent to indicate to the client that the command is finished.
```closeSession()```
This closes the session from the host side. The TCP connection also closes.
```cmdFinished()```
This signal disables both loop and more input states. It also immediately sends the IDLE frame to the client to indicate that the command is finished. Normally, you should not have to emit this signal directly because the ```CmdExecutor``` will automatically send the ```IDLE``` frame if it detects that both the loop and more inputs states are disabled after calling ```procBin()```. This signal is only useful if you need to indicate that the command is finished outside of the ```procBin()``` function.
```logout()```
This clears parameters in ```SharedObjs``` related to the currently logged in user and puts the session in a reset state with no user currently logged in. Unlike ```closeSession()```, this does not close the TCP connection.

80
docs/Host_Features.md Normal file
View File

@ -0,0 +1,80 @@
### 5.1 Host Features ###
Other than transporting data to be processed by command objects, the host have a few other built in features such as data broadcasting to/from clients connected to the host, a multi-process architecture and full user account management. The following concepts needed to be created to facilitate these specific features:
### 5.2 Host Groups And Ranks ###
Host groups are used to manage the access level of all users. Each user registered in the host must be assigned a group and each group must be assigned a host rank. The rank is numeric integer that indicates the value of the group's rank. The lower it's numeric value, the higher the level of access the users in that group have in the host with 0 being invalid. By default, the host defines the ```root``` user into a group also called ```root``` and that group has a host rank of 1; giving it the highest level of access possible in the host.
The host also defines a default ```users``` group assigned a rank of 2 and that group is also assigned as the ```initial group``` for all new accounts that are created in the host. This can be re-configured at any time using the ```host_settings``` internal command.
Some internal commands have the ability to change the user account information of other accounts. The host will in general not allow users of a lower level of access to any user information of higher access level. For example: a user of host rank ```1``` can force change another user's email address if that user's rank is ```2``` or higher but the rank ```2``` can't do the same in reverse.
Host ranks can also be assigned to the commands themselves via the command names. The ```CmdExecutor``` object uses this to determine if it's allowed to load the command object or not. By doing this, the host can be configured to allow users of certain ranks or higher access to running certain commands. For example: if a command named ```this_cmd``` is assigned a host rank of ```6```, all users with a host rank value of ```6``` or lower will have access to loading/running this command. All commands that don't have an assigned rank will be assumed a rank of 1 but all commands that define itself as rank exempt can bypass this and allow the user to load/run it regardless of the user's host rank. This would also disregard the assigned rank of the command.
### 5.3 Channels And Sub-channels ###
Channels are used to manage sub-channels and sub-channels are used to determine which clients can send/receive broadcast data. When a client broadcast data to a open sub-channel, the clients that want to receive that data will also need to have the matching sub-channel open. Channels and sub-channels can be identified by a string name or integer id. When a channel is created, the user only needs to provide a unique channel name because the host will auto generate a unique channel id attached to that name. This id is a 64bit unsigned integer and it remains constant for as long as the channel exists, even when the name changes. The channel however can't broadcast any data until a sub-channel is created with the user providing a sub-channel name unique to the channel and the host will auto generate a sub-channel id also unique to the channel. The sub-id is a 8bit unsigned integer and it also remains constant for as long as the sub-channel exists. When brocasting data, a combination of the channel and sub-channel ids are used in the ```SharedObjs``` class (```chIds``` variable) as described in section [3.4](Command_Objects.md) to route the data.
Access to opening sub-channels are managed in a way similar to the host groups and ranks. All channels have a list of host user accounts that are members of the channel, each having managed levels of access to what they can do as a member of the channel. Host users are added via invitation and the users themselves have the option to accept or decline the invitation to join the channel. Like the host rank, access levels to the channels are a numeric integer value where the lower it's value is the higher level of access the channel member will have but unlike the host rank, the access levels are not user defined. Instead, all levels are host defined and what each level can do is also host defined.
```
enum ChannelMemberLevel
{
OWNER = 1,
ADMIN = 2,
OFFICER = 3,
REGULAR = 4,
PUBLIC = 5
};
```
Below is a description of what each of these levels can do within the channel:
owner-level(1):
1. delete or rename the channel.
2. delete, create or rename sub-channels within the channel.
3. invite new users to the channel or cancel invites.
4. remove any member of the channel except your self.
5. set sub-channels' level of access.
6. add/remove read only flags to/from sub-channels.
7. update the privilege level of any member in the channel.
8. open/close sub-channels.
admin-level(2):
1. delete, create or rename sub-channels within the channel.
2. invite new users to the channel or cancel invites.
3. remove any member of channel except the owner and other admins.
4. set sub-channels' level of access.
5. add/remove read only flags to/from sub-channels.
6. update the privilege level of members up to your own level but not above.
7. open/close sub-channels.
officer-level(3):
1. invite new users to the channel or cancel invites.
2. can only remove regular members of the channel.
3. update the privilege level of members up to your own level but not above.
4. open/close sub-channels.
regular-level(4):
1. open/close sub-channels.
public-level(5):
1. open/close public sub-channels.
All sub-channels can be configured with it's own "lowest level of access" level that can make it so only certain channel members can open it. For example, the channel owner or admin can set a sub-channel's minimum level to 4 to make it so only channel regular members and above can open the sub-channel or it can be set to 5 to make it so anybody can open/close the sub-channel, affectively making it a public sub-channel.
There can only be one channel owner so if the owner decides change the privilege of any other member in the channel to owner, the current owner will automatically step down to level 2 (admin). Also note that privilege level 5 is reserved for users that are not a member of the channel and cannot be assigned to any user that are currently members of the channel.
Sub-channels can also be assigned what is called *read-only* flags. These flags are attached to the sub-channel id and privilege level. It is decoupled from all changes that could occur with the sub-channel so this means the sub-channel can get renamed or even deleted but the read-only flag would still remain. What a read-only flag actual does is make it so certain users of the matching level can listen for broadcast data but cannot send out broadcast data to the sub-channel. So a read-only flag for example can be added to a sub-channel id for privilege 5 to make it so public users can listen to the sub-channel but cannot send out anything to it.
### 5.4 Multi-Process Architecture ###
The host uses what's called a multi-process architecture which basically means each session operate in seperated processes and threads. This makes it possible for a session to crash due to a faultly command without taking down the entire host. In fact, the main process can detect this crash and attempt to restore the session automatically, up to a limited amount of attempts just so it doesn't infinite loop on crash-restore attempts.
In the code, this is done mainly in the ```Session``` class. When a client connects, a version of this class is created to operate in the main process and in it's own thread. It will then create another instance of the host and that new instance will create another ```Session``` class to operate in slave mode. The slave ```Session``` class will then start communicating with the main process ```Session``` via named pipes (```QLocalSocket```) using the same mrci frame protocol as with the client (section [1.1](Protocol.md)). The class that handles running the commands is the ```CmdExecutor``` object and that lives in the slave process where it is safe to crash without causing the host to go down.

182
docs/Internal_Commands.md Normal file
View File

@ -0,0 +1,182 @@
### 7.1 Internal Commands ###
The host is extendable via 3rd party modules but the host itself have it's own internal module that load commands with direct access to the host database and several internal power functions that external commands would otherwise not have direct access to.
* [auth](intern_commands/auth.md) - login to the host using a registered user account name or email address.
* [ls_cmds](intern_commands/ls_cmds.md) - list all available commands for your current session.
* [my_info](intern_commands/my_info.md) - display information about your current session and your account.
* [recover_acct](intern_commands/recover_acct.md) - reset a user account password.
* [request_pw_reset](intern_commands/request_pw_reset.md) - request a password reset for a user account.
* [accept_ch](intern_commands/accept_ch.md) - accept an invite to a channel to become a regular member of it.
* [add_acct](intern_commands/add_acct.md) - create a new host user account.
* [add_ban](intern_commands/add_ban.md) - add an ip address to the host ban list.
* [add_cert](intern_commands/add_cert.md) - install a new SSL/TLS cert into the host from a local cert and private key file.
* [add_ch](intern_commands/add_ch.md) - create a new channel.
* [add_group](intern_commands/add_group.md) - create a new host group.
* [add_mod](intern_commands/add_mod.md) - upload a new module to install into the host.
* [add_ranked_cmd](intern_commands/add_ranked_cmd.md) - assign a rank to a command object name.
* [add_rdonly_flag](intern_commands/add_rdonly_flag.md) - add a read only flag to a certain sub-channel and privilege level.
* [add_sub_ch](intern_commands/add_sub_ch.md) - create a new sub-channel within a channel.
* [cast](intern_commands/cast.md) - broadcast text/data to all sessions listening to any matching sub-channels.
* [cert_info](intern_commands/cert_info.md) - display detailed information about an installed SSL/TLS certificate.
* [ch_owner_override](intern_commands/ch_owner_override.md) - set/unset the channel owner override flag for your current session.
* [close_host](intern_commands/close_host.md) - close the host instance.
* [close_sub_ch](intern_commands/close_sub_ch.md) - close a sub-channel for your current session.
* [cmd_info](intern_commands/cmd_info.md) - display detailed information about a command.
* [decline_ch](intern_commands/decline_ch.md) - decline an invite to a channel.
* [find_ch](intern_commands/find_ch.md) - search for channels within the host based on the channel name or channel id.
* [force_set_email](intern_commands/force_set_email.md) - overwrite/change the email address of another user's account.
* [fs_cd](intern_commands/fs_cd.md) - display or change the current directory for the current session.
* [fs_copy](intern_commands/fs_copy.md) - copy a file system object (file,directory,symlink) from one location to another.
* [fs_delete](intern_commands/fs_delete.md) - attempt to delete a file system object (file,directory,symlink) in the host.
* [fs_download](intern_commands/fs_download.md) - download a single file from the host.
* [fs_info](intern_commands/fs_info.md) - get detailed information about a file system object (file,directory,symlink) in the host.
* [fs_list](intern_commands/fs_list.md) - list all files or sub-directories in a directory.
* [fs_mkpath](intern_commands/fs_mkpath.md) - attempt to create a directory and all sub-directories of a given path.
* [fs_move](intern_commands/fs_move.md) - move/rename a file system object (file,directory,symlink) from one location to another.
* [fs_upload](intern_commands/fs_upload.md) - upload a single file to the host.
* [host_config](intern_commands/host_config.md) - view/change various host settings.
* [host_info](intern_commands/host_info.md) - display system information about the host.
* [invite_to_ch](intern_commands/invite_to_ch.md) - invite a host user to join a channel.
* [is_email_verified](intern_commands/is_email_verified.md) - check if your email address is verified.
* [lock_acct](intern_commands/lock_acct.md) - lock user account.
* [ls_act_log](intern_commands/ls_act_log.md) - display or manage the client activity log.
* [ls_auth_log](intern_commands/ls_auth_log.md) - display or manage the host authorization activity log.
* [ls_bans](intern_commands/ls_bans.md) - display or manage the host ip address ban table.
* [ls_certs](intern_commands/ls_certs.md) - display a list of all SSL/TLS certificates installed in the host database.
* [ls_ch_members](intern_commands/ls_ch_members.md) - list all members in a channel.
* [ls_chs](intern_commands/ls_chs.md) - list all channels you are currently a member of and all pending invites.
* [ls_dbg](intern_commands/ls_dbg.md) - display debug messages from the host instance and all session instances.
* [ls_groups](intern_commands/ls_groups.md) - list all groups currently registered in the host.
* [ls_mods](intern_commands/ls_mods.md) - list all available modules currently installed in the host.
* [ls_open_chs](intern_commands/ls_open_chs.md) - list all of the sub-channels that are currently open.
* [ls_p2p](intern_commands/ls_p2p.md) - list all p2p connections and pending p2p request you currently have.
* [ls_ranked_cmds](intern_commands/ls_ranked_cmds.md) - list all command names with assigned host ranks.
* [ls_rdonly_flags](intern_commands/ls_rdonly_flags.md) - list all read only flags currently present for a channel.
* [ls_sub_chs](intern_commands/ls_sub_chs.md) - list all sub-channels within a channel you currently a member of.
* [ls_users](intern_commands/ls_users.md) - list all users currently registered in the host database.
* [open_sub_ch](intern_commands/open_sub_ch.md) - open a sub-channel to send/receive broadcasted data to/from other peers.
* [p2p_close](intern_commands/p2p_close.md) - close the p2p connection with the client given in this command or decline a p2p request.
* [p2p_open](intern_commands/p2p_open.md) - accept the p2p request you may have received from another client connected to the host.
* [p2p_request](intern_commands/p2p_request.md) - send out a p2p request to the client session id given in this command.
* [pause](intern_commands/pause.md) - pause the current task that the command is running.
* [ping_peers](intern_commands/ping_peers.md) - ping all peer sessions with any matching sub-channels to return information about themselves to you.
* [preview_email](intern_commands/preview_email.md) - preview the confirmation or password reset emails with dummy values.
* [remove_ch_member](intern_commands/remove_ch_member.md) - remove a user as a member of a channel you currently a member of or cancel an invite.
* [rename_ch](intern_commands/rename_ch.md) - rename a channel.
* [rename_sub_ch](intern_commands/rename_sub_ch.md) - rename a sub-channel within a channel.
* [request_new_pw](intern_commands/request_new_pw.md) - enable/disable a password change request for a user on next login.
* [request_new_user_name](intern_commands/request_new_user_name.md) - enable/disable a user name change request for a user on next login.
* [restart_host](intern_commands/restart_host.md) - re-start the host instance.
* [resume](intern_commands/resume.md) - resumes the current task that the command is running.
* [rm_acct](intern_commands/rm_acct.md) - delete a user account from the host database.
* [rm_ban](intern_commands/rm_ban.md) - remove an ip address from the ban list.
* [rm_cert](intern_commands/rm_cert.md) - remove the SSL/TLS cert associated with the given common name.
* [rm_ch](intern_commands/rm_ch.md) - permanently remove a channel and all of it's sub-shannels from the host.
* [rm_mod](intern_commands/rm_mod.md) - uninstall a module from the host.
* [rm_ranked_cmd](intern_commands/rm_ranked_cmd.md) - remove a rank from a command object name.
* [rm_rdonly_flag](intern_commands/rm_rdonly_flag.md) - remove a read only flag from a certain sub-channel privilege level combination.
* [rm_sub_ch](intern_commands/rm_sub_ch.md) - remove a sub-channel within a channel.
* [set_active_flag](intern_commands/set_active_flag.md) - set or unset the active update flag of a sub-channel.
* [set_disp_name](intern_commands/set_disp_name.md) - change your account display name.
* [set_email](intern_commands/set_email.md) - change the user account email address.
* [set_email_template](intern_commands/set_email_template.md) - set the email template used by the host to send emails for user account resets and confirmations.
* [set_group](intern_commands/set_group.md) - change a user account's group.
* [set_group_rank](intern_commands/set_group_rank.md) - set the host rank of a group.
* [set_member_level](intern_commands/set_member_level.md) - set the user privilege levels of a channel member. (lower the value, the higher the privilege)
* [set_pw](intern_commands/set_pw.md) - change your account password.
* [set_sub_ch_level](intern_commands/set_sub_ch_level.md) - set the lowest privilege level that members need to be in order to open a certain sub-channel.
* [set_user_name](intern_commands/set_user_name.md) - change your account user name.
* [term](intern_commands/term.md) - terminate the current task that the command is running.
* [to_peer](intern_commands/to_peer.md) - send/receive any data directly with a client connected to the host that has accepted your p2p request or the peer's p2p request.
* [trans_group](intern_commands/trans_group.md) - transfer all user accounts from one group to another.
* [verify_email](intern_commands/verify_email.md) - verify your email address by sending a confirmation code to it.

621
docs/LICENSE.md Normal file
View File

@ -0,0 +1,621 @@
GNU GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble
The GNU General Public License is a free, copyleft license for
software and other kinds of works.
The licenses for most software and other practical works are designed
to take away your freedom to share and change the works. By contrast,
the GNU General Public License is intended to guarantee your freedom to
share and change all versions of a program--to make sure it remains free
software for all its users. We, the Free Software Foundation, use the
GNU General Public License for most of our software; it applies also to
any other work released this way by its authors. You can apply it to
your programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.
To protect your rights, we need to prevent others from denying you
these rights or asking you to surrender the rights. Therefore, you have
certain responsibilities if you distribute copies of the software, or if
you modify it: responsibilities to respect the freedom of others.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received. You must make sure that they, too, receive
or can get the source code. And you must show them these terms so they
know their rights.
Developers that use the GNU GPL protect your rights with two steps:
(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.
For the developers' and authors' protection, the GPL clearly explains
that there is no warranty for this free software. For both users' and
authors' sake, the GPL requires that modified versions be marked as
changed, so that their problems will not be attributed erroneously to
authors of previous versions.
Some devices are designed to deny users access to install or run
modified versions of the software inside them, although the manufacturer
can do so. This is fundamentally incompatible with the aim of
protecting users' freedom to change the software. The systematic
pattern of such abuse occurs in the area of products for individuals to
use, which is precisely where it is most unacceptable. Therefore, we
have designed this version of the GPL to prohibit the practice for those
products. If such problems arise substantially in other domains, we
stand ready to extend this provision to those domains in future versions
of the GPL, as needed to protect the freedom of users.
Finally, every program is threatened constantly by software patents.
States should not allow patents to restrict development and use of
software on general-purpose computers, but in those that do, we wish to
avoid the special danger that patents applied to a free program could
make it effectively proprietary. To prevent this, the GPL assures that
patents cannot be used to render the program non-free.
The precise terms and conditions for copying, distribution and
modification follow.
TERMS AND CONDITIONS
0. Definitions.
"This License" refers to version 3 of the GNU General Public License.
"Copyright" also means copyright-like laws that apply to other kinds of
works, such as semiconductor masks.
"The Program" refers to any copyrightable work licensed under this
License. Each licensee is addressed as "you". "Licensees" and
"recipients" may be individuals or organizations.
To "modify" a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of an
exact copy. The resulting work is called a "modified version" of the
earlier work or a work "based on" the earlier work.
A "covered work" means either the unmodified Program or a work based
on the Program.
To "propagate" a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy. Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.
To "convey" a work means any kind of propagation that enables other
parties to make or receive copies. Mere interaction with a user through
a computer network, with no transfer of a copy, is not conveying.
An interactive user interface displays "Appropriate Legal Notices"
to the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License. If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.
1. Source Code.
The "source code" for a work means the preferred form of the work
for making modifications to it. "Object code" means any non-source
form of a work.
A "Standard Interface" means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.
The "System Libraries" of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form. A
"Major Component", in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.
The "Corresponding Source" for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities. However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work. For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.
The Corresponding Source need not include anything that users
can regenerate automatically from other parts of the Corresponding
Source.
The Corresponding Source for a work in source code form is that
same work.
2. Basic Permissions.
All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met. This License explicitly affirms your unlimited
permission to run the unmodified Program. The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work. This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not
convey, without conditions so long as your license otherwise remains
in force. You may convey covered works to others for the sole purpose
of having them make modifications exclusively for you, or provide you
with facilities for running those works, provided that you comply with
the terms of this License in conveying all material for which you do
not control copyright. Those thus making or running the covered works
for you must do so exclusively on your behalf, under your direction
and control, on terms that prohibit them from making any copies of
your copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under
the conditions stated below. Sublicensing is not allowed; section 10
makes it unnecessary.
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.
When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such circumvention
is effected by exercising rights under this License with respect to
the covered work, and you disclaim any intention to limit operation or
modification of the work as a means of enforcing, against the work's
users, your or third parties' legal rights to forbid circumvention of
technological measures.
4. Conveying Verbatim Copies.
You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.
5. Conveying Modified Source Versions.
You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these conditions:
a) The work must carry prominent notices stating that you modified
it, and giving a relevant date.
b) The work must carry prominent notices stating that it is
released under this License and any conditions added under section
7. This requirement modifies the requirement in section 4 to
"keep intact all notices".
c) You must license the entire work, as a whole, under this
License to anyone who comes into possession of a copy. This
License will therefore apply, along with any applicable section 7
additional terms, to the whole of the work, and all its parts,
regardless of how they are packaged. This License gives no
permission to license the work in any other way, but it does not
invalidate such permission if you have separately received it.
d) If the work has interactive user interfaces, each must display
Appropriate Legal Notices; however, if the Program has interactive
interfaces that do not display Appropriate Legal Notices, your
work need not make them do so.
A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
"aggregate" if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit. Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.
6. Conveying Non-Source Forms.
You may convey a covered work in object code form under the terms
of sections 4 and 5, provided that you also convey the
machine-readable Corresponding Source under the terms of this License,
in one of these ways:
a) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by the
Corresponding Source fixed on a durable physical medium
customarily used for software interchange.
b) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by a
written offer, valid for at least three years and valid for as
long as you offer spare parts or customer support for that product
model, to give anyone who possesses the object code either (1) a
copy of the Corresponding Source for all the software in the
product that is covered by this License, on a durable physical
medium customarily used for software interchange, for a price no
more than your reasonable cost of physically performing this
conveying of source, or (2) access to copy the
Corresponding Source from a network server at no charge.
c) Convey individual copies of the object code with a copy of the
written offer to provide the Corresponding Source. This
alternative is allowed only occasionally and noncommercially, and
only if you received the object code with such an offer, in accord
with subsection 6b.
d) Convey the object code by offering access from a designated
place (gratis or for a charge), and offer equivalent access to the
Corresponding Source in the same way through the same place at no
further charge. You need not require recipients to copy the
Corresponding Source along with the object code. If the place to
copy the object code is a network server, the Corresponding Source
may be on a different server (operated by you or a third party)
that supports equivalent copying facilities, provided you maintain
clear directions next to the object code saying where to find the
Corresponding Source. Regardless of what server hosts the
Corresponding Source, you remain obligated to ensure that it is
available for as long as needed to satisfy these requirements.
e) Convey the object code using peer-to-peer transmission, provided
you inform other peers where the object code and Corresponding
Source of the work are being offered to the general public at no
charge under subsection 6d.
A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.
A "User Product" is either (1) a "consumer product", which means any
tangible personal property which is normally used for personal, family,
or household purposes, or (2) anything designed or sold for incorporation
into a dwelling. In determining whether a product is a consumer product,
doubtful cases shall be resolved in favor of coverage. For a particular
product received by a particular user, "normally used" refers to a
typical or common use of that class of product, regardless of the status
of the particular user or of the way in which the particular user
actually uses, or expects or is expected to use, the product. A product
is a consumer product regardless of whether the product has substantial
commercial, industrial or non-consumer uses, unless such uses represent
the only significant mode of use of the product.
"Installation Information" for a User Product means any methods,
procedures, authorization keys, or other information required to install
and execute modified versions of a covered work in that User Product from
a modified version of its Corresponding Source. The information must
suffice to ensure that the continued functioning of the modified object
code is in no case prevented or interfered with solely because
modification has been made.
If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information. But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).
The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or updates
for a work that has been modified or installed by the recipient, or for
the User Product in which it has been modified or installed. Access to a
network may be denied when the modification itself materially and
adversely affects the operation of the network or violates the rules and
protocols for communication across the network.
Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.
7. Additional Terms.
"Additional permissions" are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law. If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it. (Additional permissions may be written to require their own
removal in certain cases when you modify the work.) You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders of
that material) supplement the terms of this License with terms:
a) Disclaiming warranty or limiting liability differently from the
terms of sections 15 and 16 of this License; or
b) Requiring preservation of specified reasonable legal notices or
author attributions in that material or in the Appropriate Legal
Notices displayed by works containing it; or
c) Prohibiting misrepresentation of the origin of that material, or
requiring that modified versions of such material be marked in
reasonable ways as different from the original version; or
d) Limiting the use for publicity purposes of names of licensors or
authors of the material; or
e) Declining to grant rights under trademark law for use of some
trade names, trademarks, or service marks; or
f) Requiring indemnification of licensors and authors of that
material by anyone who conveys the material (or modified versions of
it) with contractual assumptions of liability to the recipient, for
any liability that these contractual assumptions directly impose on
those licensors and authors.
All other non-permissive additional terms are considered "further
restrictions" within the meaning of section 10. If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term. If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions;
the above requirements apply either way.
8. Termination.
You may not propagate or modify a covered work except as expressly
provided under this License. Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly and
finally terminates your license, and (b) permanently, if the copyright
holder fails to notify you of the violation by some reasonable means
prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.
9. Acceptance Not Required for Having Copies.
You are not required to accept this License in order to receive or
run a copy of the Program. Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance. However,
nothing other than this License grants you permission to propagate or
modify any covered work. These actions infringe copyright if you do
not accept this License. Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.
10. Automatic Licensing of Downstream Recipients.
Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License. You are not responsible
for enforcing compliance by third parties with this License.
An "entity transaction" is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations. If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License. For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.
11. Patents.
A "contributor" is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based. The
work thus licensed is called the contributor's "contributor version".
A contributor's "essential patent claims" are all patent claims
owned or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version. For
purposes of this definition, "control" includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.
In the following three paragraphs, a "patent license" is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement). To "grant" such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.
If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients. "Knowingly relying" means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.
A patent license is "discriminatory" if it does not include within
the scope of its coverage, prohibits the exercise of, or is
conditioned on the non-exercise of one or more of the rights that are
specifically granted under this License. You may not convey a covered
work if you are a party to an arrangement with a third party that is
in the business of distributing software, under which you make payment
to the third party based on the extent of your activity of conveying
the work, and under which the third party grants, to any of the
parties who would receive the covered work from you, a discriminatory
patent license (a) in connection with copies of the covered work
conveyed by you (or copies made from those copies), or (b) primarily
for and in connection with specific products or compilations that
contain the covered work, unless you entered into that arrangement,
or that patent license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.
12. No Surrender of Others' Freedom.
If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot convey a
covered work so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you may
not convey it at all. For example, if you agree to terms that obligate you
to collect a royalty for further conveying from those to whom you convey
the Program, the only way you could satisfy both those terms and this
License would be to refrain entirely from conveying the Program.
13. Use with the GNU Affero General Public License.
Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU Affero General Public License into a single
combined work, and to convey the resulting work. The terms of this
License will continue to apply to the part which is the covered work,
but the special requirements of the GNU Affero General Public License,
section 13, concerning interaction through a network will apply to the
combination as such.
14. Revised Versions of this License.
The Free Software Foundation may publish revised and/or new versions of
the GNU General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the
Program specifies that a certain numbered version of the GNU General
Public License "or any later version" applies to it, you have the
option of following the terms and conditions either of that numbered
version or of any later version published by the Free Software
Foundation. If the Program does not specify a version number of the
GNU General Public License, you may choose any version ever published
by the Free Software Foundation.
If the Program specifies that a proxy can decide which future
versions of the GNU General Public License can be used, that proxy's
public statement of acceptance of a version permanently authorizes you
to choose that version for the Program.
Later license versions may give you additional or different
permissions. However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.
15. Disclaimer of Warranty.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. Limitation of Liability.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
17. Interpretation of Sections 15 and 16.
If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.
END OF TERMS AND CONDITIONS

80
docs/Protocol.md Normal file
View File

@ -0,0 +1,80 @@
### 1.1 The Protocol ###
The main goal of this application is to transport data from remote TCP clients to the [Command_Objects](Command_Objects.md) defined in the host. How the data processed and/or returned back to the client depends entirely on the type of data being transported or the command object itself. The format that the host understands for data transport is referred to as MRCI frames as described below in section 1.2.
Before any MRCI frames can be transported, the host need to be made aware of the version of the host that the client supports and the client needs to be made aware of the host current version. This is done by having the client send a fixed length client header when it successfully connects to the host and the host will reply with it's own fixed length host header. Descriptions of these headers can be found in sections 1.4 and 1.5.
### 1.2 MRCI Frames ###
MRCI frames are a data structure that allow the TCP clients to communicate with commands objects and various other objects defined in the MRCI host.
```
Format:
[type_id][cmd_id][data_len][payload]
type_id - 1byte - 8bit little endian integer type id of the payload.
cmd_id - 2bytes - 16bit little endian integer command object id.
data_len - 3bytes - 24bit little endian integer size of the payload.
payload - variable - the actual data to be processed.
```
A full description of the type id's can be found in the [Type_IDs.md](Type_IDs.md) document.
### 1.3 Versioning System ###
The host uses the typical 3 number versioning system: Major.Minor.Patch
* **Major** - this indicates any major changes to the code of the application that renders versions of different majors incompatible with each other.
* **Minor** - this indicates only minor changes to the code that may require a few conditional blocks to maintain compatibility.
* **Patch** - this indicates changes that won't require any behaviour changes at all to maintain compatibility.
Any increments to the major resets the minor and patch to 0. Any 3rd party client applications connecting to a MRCI host need to be aware of this versioning but does not need to adopt it as it's own version number.
### 1.4 Client Header ###
```
Format:
[tag][major][minor][patch][appName][coName]
tag - 4bytes - 0x4D, 0x52, 0x43, 0x49 (MRCI)
major - 2bytes - 16bit little endian unsigned int
minor - 2bytes - 16bit little endian unsigned int
patch - 2bytes - 16bit little endian unsigned int
appName - 128bytes - UTF16LE string (padded with spaces)
coName - 272bytes - UTF16LE string (padded with spaces)
```
notes:
* The **tag** is just a fixed ascii string "MRCI" that indicates to the host that the client is indeed attempting to use the MRCI protocol.
* The **appName** is the name of the client application that is connected to the host. It can also contain the client's app version if needed because it doesn't follow any particular standard. This string is accessable to all command objects so the commands themselves can be made aware of what app the user is currently using.
* The **coName** is the common name of a SSL certificate that is currently installed in the host. Depending on how the host is configured, it can contain more than one installed SSL cert so coName can be used by clients as a way to request which one of the SSL certs to use during the SSL handshake.
### 1.5 Host Header ###
```
Format:
[reply][major][minor][patch][sesId]
reply - 1byte - 8bit little endian unsigned int
major - 2bytes - 16bit little endian unsigned int
minor - 2bytes - 16bit little endian unsigned int
patch - 2bytes - 16bit little endian unsigned int
sesId - 28bytes - 224bit sha3 hash
```
notes:
* **reply** is a numeric value that the host returns in it's header to communicate to the client the result of it's evaluation of the client's header.
* reply = 1, means the client version is acceptable and it does not need to take any further action.
* reply = 2, means the client version is acceptable but the host will now send it's Pem formatted SSL cert data in a ```HOST_CERT``` mrci frame just after sending it's header. After receiving the cert, the client will then need to send a STARTTLS signal using this cert.
* reply = 3, means the client version is not supported by the host and the session will end shortly.
* reply = 4, means the host was unable to load the SSL cert associated with the common name sent by the client. The session will auto close at this point.
* **sesId** is the session id. It is a unique 224bit sha3 hash generated against the current date and time of session creation (down to the msec) and the machine id. This can be used by the host and client to uniquely identify the current session or past sessions.

90
docs/README.md Normal file
View File

@ -0,0 +1,90 @@
# MRCI #
(Modular Remote Command Interpreter) is a command interpreter primarily designed to provide remote service to connected clients, whether text based or any kind of data. As the name implies, it is expandable via 3rd party modules by adding addtional commands that remote clients can run on the host. It has a fully feasured user account management system with access control to certain commands for certain user groups. All persistent data is handled by a SQLite database and all remote connections are handled via TCP and encrypted in SSL/TLS.
### Usage ###
```
Usage: mrci <arguments>
<Arguments>
-help : display usage information about this application.
-start : start a new host instance in the background.
-stop : stop the current host instance if one is currently running.
-about : display versioning/warranty information about this application.
-addr {ip_address:port} : set the listening address and port for TCP clients.
-status : display status information about the host instance if it is currently running.
-reset_root : reset the root account password to default.
-executor : this starts a command executor instance. this is normally for internal use only.
-host : this starts a blocking host instance. this is normally for internal use only.
```
Other than that, the host can only be managed via a connected client that supports text input/output so the host application is always listening for clients while running entirely in the background. By default, the host listen for clients on address 127.0.0.1 and port 35516. Just like any linux OS, the host will have an administrative user called root along with a group also called root. This account can be used to modify anything on the host without restriction. The default password set to (R00tPa$$w0rd) when logging in for the first time as root, the host will require you to change the password before continuing.
### More Than Just a Command Interpreter ###
Typical use for a MRCI host is to run commands that clients ask it to run, very similar to what you see in terminal emulators. It however does have a few feasures typically not seen in local terminals:
* Broadcast any type of data to all peers connected to the host.
* Run remote commands on connected peers.
* Host object positioning data for peers (online games do this).
* Send data to/from a peer client directly.
* Fully feasured builtin user account management.
* Built in permissions and command access management.
* Host limits management (max concurrent users, max failed password attempts, etc...).
* Account recovery emailing in case of forgotten passwords. **
* Acesss to various logs.
* Built in host file management (copy, move, delete, etc...).
* Built in file upload/download support.
Because the host is modular, the things you can customize it to do is almost limitless by simply adding more commands.
** The email system of this application depends on external email clients that run on the command line. The default is [mutt](http://www.mutt.org/). If you want emails to work out of the box, consider installing and configuring mutt. It just needs to be configured with a smtp account to send emails with. You don't have to use mutt though, the host does have options to change the email client to any other application that has a command line interface.
### Documentation ###
[1.1 The Protocol](Protocol.md)
[2.1 Command Loaders](Command_Loaders.md)
[3.1 Command Objects](Command_Objects.md)
[4.1 Type IDs](Type_IDs.md)
[5.1 Host Features](Host_Features.md)
[6.1 Async Commands](Async.md)
[7.1 Internal Commands](Internal_Commands.md)
### Development Setup ###
Linux Required Packages:
```
qtbase5-dev
libssl-dev
gcc
make
makeself
```
### Build From Source (Linux) ###
Linux_build.sh is a custom script designed to build this project from the source code using qmake, make and makeself. You can pass 2 optional arguments:
1. The path to the QT bin folder in case you want to compile with a QT install not defined in PATH.
2. Path of the output makeself file (usually has a .run extension). If not given, the outfile will be named mrci-1.0.0.run in the source code folder.
Build:
```
cd /path/to/source/code
sh ./linux_build.sh
```
Install:
```
chmod +x ./mrci-1.0.0.run
./mrci-1.0.0.run
```
The makeself installer not only installs the application but also installs it as a service if the target linux system supports systemd.
Start/Stop the service:
```
sudo systemctl start mrci@$USER
sudo systemctl stop mrci@$USER
```

221
docs/Type_IDs.md Normal file
View File

@ -0,0 +1,221 @@
### 4.1 Type IDs ###
All mrci frames transferred throughout this application are usually passed into various functions using a ```uchar``` numeric value to indicate the type of data being passed with the ```QByteArray``` that are also usually passed into the functions. The type id enum values are as follows:
```
enum TypeID
{
GEN_FILE = 30,
TEXT = 31,
ERR = 32,
PRIV_TEXT = 33,
IDLE = 34,
HOST_CERT = 35,
FILE_INFO = 36,
PEER_INFO = 37,
MY_INFO = 38,
PEER_STAT = 39,
P2P_REQUEST = 40,
P2P_CLOSE = 41,
P2P_OPEN = 42,
BYTES = 43,
SESSION_ID = 44,
NEW_CMD = 45,
CMD_ID = 46,
BIG_TEXT = 47
};
```
### 4.2 Type Descriptions ###
```TEXT```
This is text that can be displayed directly to the user or pass arguments for the command object to process.
format: ```[UTF-16LE_string] (no BOM)```
```GEN_FILE```
This is a file transfer type id that can be used to transfer any type of file type (music, photos, documents, etc...). It operates in its own protocol of sorts. The 1st GEN_FILE frame received by the host or client is TEXT parameters similar to what you see in terminal command lines with at least one of the arguments listed below. The next set of GEN_FILE frames received by the host or client is then the binary data that needs to be written to an open file or streamed until the limit defined in -len is meet.
The host or the client can be set as the sender or receiver of the GEN_FILE binary data. Which ever is designated as the receiver by the TEXT parameters need to send an empty GEN_FILE frame to start the process. An example if this can be found in section 4.3.
arguments:
* **-len (int)** | this is the integer value of the file size or amount of bytes to read/write.
* **-offset (int)** | this integer position tells where in the source or destination file to start reading/writing.
* **-client_file** (string) | this is the file path to the source/destination file in the client's file system.
* **-remote_file** (string) | this is the file path to the source/destination file in the host file system.
* **-single_step** | the presents of this argument tells both the client and host to operate in single step mode. single step mode causes the receiver of the binary data whether host or client to send an empty GEN_FILE frame after successfully receiving the data. this then tells the sender to send the next GEN_FILE frame containing binary data for the file and the cycle continues until len is meet. if this argument is not found, the sender can simply send all GEN_FILE data without waiting for an empty GEN_FILE from the receiver.
* **-to_host** | this argument should only come from host and it will define the client as the sender and the host as the receiver.
* **-from_host** | opposite affect to *-to_host*. it defines the host as the sender and the client as the receiver.
* **-truncate** | this indicates to whoever is the receiver to truncate the file being written to.
* **-force** | in some cases, the receiver might need to overwrite the target file. the presents of this argument tells it to overwrite without asking the user. the host should never send this argument and the client should ignore it if it is received from the host.
```ERR```
This type id is similar to TEXT except it indicates that this is an error message that can be displayed directly to the user if needed.
```PRIV_TEXT```
This id can be treated exactly like TEXT except this should tell the client to hide or do not echo the next TEXT data that the host is expecting, like a password or other sensitive text data.
```BIG_TEXT```
Also formatted exactly like TEXT but this indicates to the client that this is a large body of text that is recommended to be word wrapped when displaying to the user. It can contain line breaks so clients are also recommended to honor those line breaks.
```IDLE```
This doesn't carry any actual data, instead this indicates that the command id that sent it has finished it's task. Commands objects are not allowed to send this directly, the ```CmdExecutor``` will handle it.
```HOST_CERT```
Just as the name implies, this data type is used by the host to send the host SSL certificate while setting up an SSL connection.
```FILE_INFO```
This is a data structure that carries information about a file system object (file,dir,link).
```
format:
1. bytes[0] - flags (8bit little endian uint)
2. bytes[1-8] - creation time in msec since Epoch UTC (64bit little endian uint)
3. bytes[9-16] - modification time in msec since Epoch UTC (64bit little endian uint)
4. bytes[17-24] - file size (64bit little endian uint)
5. bytes[25-variable] - file name (UTF16-LE string, 16bit terminated)
6. bytes[variable] - symmlink target if it is a symmlink (UTF16-LE string, 16bit terminated)
notes:
1. 16bit terminated UTF-16LE strings are basically
terminated by 2 bytes of 0x00.
2. the symmlink target is empty if not a symmlink but
the terminator should still be present.
flags:
1. bit 0 - true if the object is a file
2. bit 1 - true if the object is a directory
3. bit 2 - true if the object is a symmlink
4. bit 3 - true if the current user have read permissions
5. bit 4 - true if the current user have write permissions
6. bit 5 - true if the current user have execute permissions
7. bit 6 - true if the object exist in the file system. if symmlink,
this determines if the symm target exists or not.
```
```PEER_INFO```
This carry some user account and session information about a peer client connected to the host.
```
format:
1. bytes[0-27] 28bytes - session id (224bit hash)
2. bytes[28-59] 32bytes - user id (256bit hash)
3. bytes[60-107] 48bytes - user name (TEXT - padded with empty spaces)
4. bytes[108-235] 128bytes - app name (TEXT - padded with empty spaces)
5. bytes[236-299] 64bytes - disp name (TEXT - padded with empty spaces)
notes:
1. the session id is unique to the peer's session connection only. it
can change upon reconnection.
2. the user id is unique to the peer's user account. is stays constant
even when the user name changes and across all clients logged into
the same account.
3. the display name is the preffered display name of the peer. clients
are encouraged to use this rather than the user name when displaying
peer info to the user. if empty, it's ok to just fall back to the user
name.
```
```MY_INFO```
This contains all of the information found in ```PEER_INFO``` for the local session but also includes the following:
```
format:
1. bytes[300-427] 128bytes - email (TEXT - padded with empty spaces)
2. bytes[428-451] 24bytes - group name (TEXT - padded with empty spaces)
3. bytes[452] 1byte - is email confirmed? (0x00 false, 0x01 true)
```
```NEW_CMD```
This contains information about a new command that was added to the current session.
```
format:
1. bytes[0-1] 2bytes - 16bit LE unsigned int (command id)
2. bytes[2] 1byte - bool (0x01 or 0x00) (handles gen file)
3. bytes[3-130] 128bytes - command name (TEXT - padded with empty spaces)
4. bytes[131-258] 128bytes - library name (TEXT - padded with empty spaces)
notes:
1. the handles gen file flag is a single byte 0x01 to indicate true and
0x00 to indicate false. clients need to be aware of which command
handles the GEN_FILE mini protocol because it requires user input at
both ends (host and client).
2. the library name is what ever is returned by the command object's
ExternCommand::libText() function. this can contain the module name
and/or extra informaion the client can use to identify the command.
```
```CMD_ID```
This type id carries a 16bit unsigned LE int representing a command id.
format: ```2bytes - 16bit LE unsigned int (command id)```
```PEER_STAT```
This contain status information of a peer client when the peer changes sub-channels or disconnects from the host.
```
format:
1. bytes[0-27] 28bytes - session id (224bit hash)
2. bytes[28-81] 54bytes - channel-sub ids
3. bytes[82] 1byte - is disconnected? (0x00 false, 0x01 true)
notes:
1. if (is disconnected) is set true (0x01) the session id will no longer
be valid for that peer client so you should not make anymore attempts
to send data to it.
2. channel-sub ids is a string of 9byte channel-sub id combinations at
a fixed length of 54bytes (padded with 0x00). this indicates what
channels-subs the peer currently have open if the peer's channel ids
no longer match with your session, it can be considered inactive or
disconnected since you will no longer send/receive data with this peer.
```
```SESSION_ID```
This is a fixed length 28byte(224bit) sha3 hash of a client's session id connected to the host. This is unique to just the client's tcp connection with the host. This can change upon re-connection.
format: ```28bytes - session id (224bit sha3 hash)```
```P2P_REQUEST```
This is formatted extactly like ```PEER_INFO``` except this is allowed to be sent directly to the target peer without restriction when using the ```ExternCommand::toPeer()``` signal ([Command_Objects.md](Command_Objects.md), section 2.5). It will be up to the target peer to respond with a ```P2P_OPEN``` for the host to then unrestrict ```toPeer()``` so it will then be able to send/received other TypeIDs with this peer until ```P2P_CLOSE``` is sent/received. ```P2P_CLOSE``` can also be sent to decline the request. When sending this TypeID, the ```CmdExecutor``` will ignore the data passed into ```toPeer()``` from the command object and substitute with it's own generated ```P2P_REQUEST``` to prevent fraudulent request from getting sent out to all sessions; because of this, it is ok and preferable to send an empty ```P2P_REQUEST``` with the ```toPeer()``` signal.
```P2P_OPEN```
This contains a 28byte session id hash of the peer session that you or the peer will allow direct communication with when using the ```ExternCommand::toPeer()``` signal.
format: ```28bytes - session id (224bit sha3 hash)```
```P2P_CLOSE```
This contains a 28byte session id hash of the peer session that you or the peer want to close direct communication with when using the ```ExternCommand::toPeer()``` signal.
format: ```28bytes - session id (224bit sha3 hash)```
```BYTES```
This contains arbitrary binary data of any format that is not specialized for any internal objects in the host.
### 4.3 GEN_FILE Example ###
Setup:
* The host has a command called *upload_file* with a command id of *768* and handles the ```GEN_FILE``` data type.
* The client has a file called */home/foo/bar.mp3* and wants to upload it to the host file */home/host/music/bar.mp3* and the client knows the file size is 512bytes.
To upload the file, the client calls command id *768* with the following text arguments (must still be sent as a GEN_FILE):
```-client_file "/home/foo/bar.mp3" -remote_file "/home/host/music/bar.mp3" -len 512```
The host will then return the following the text arguments to the client (also sent as a GEN_FILE):
```-to_host```
This argument from the host designates it as the receiver so it will be up to the host to send an empty ```GEN_FILE``` to indicate to the client that it was ready to start receiving binary data from the client to write to */home/host/music/bar.mp3*. If that file already exists, the host will need to ask the user to overwrite or not.
If the host indicates that it's ready for the upload, the client can then simply read 512 bytes from */home/foo/bar.mp3* and send the read bytes to the host command id *768* as a ```GEN_FILE```.
The host will then write the bytes received from the client to */home/host/music/bar.mp3* and then auto terminate the command since 512 bytes has been meet.

11
docs/intern_commands/accept_ch.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
accept an invite to a channel to become a regular member of it.
### IO ###
```[-ch_name (text)]/[text]```
### Description ###
accept an invite to the join the channel given in -ch_name. this will fail and do nothing if you do not currently have an existing invite to the channel. once accepted, you will be added to the channel's member list initiated as a regular-level(4).

11
docs/intern_commands/add_acct.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
create a new host user account.
### IO ###
```[-name (text) -email (text) {-disp (text)}]/[text]```
### Description ###
this creates a new user account with the user name given in -name and an email address used for account recovery in -email. the command will fail if the user name already exists. you can pass the optional -disp to set the display name for the new user account. the display name can be used by clients to present the user account to other clients without showing the true user name or make it easier for users to identify each other since the display name is not restricted by uniqueness. the display name can be anything; it's only restricted to 32 chars or less.

11
docs/intern_commands/add_ban.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
add an ip address to the host ban list.
### IO ###
```[-ip (text)]/[text]```
### Description ###
add an ip address or its integer representative given in -ip to the host ban list that will prevent any client from connecting to the host with that ip address.

11
docs/intern_commands/add_cert.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
install a new SSL/TLS cert into the host from a local cert and private key file.
### IO ###
```[-name (text) -cert (path) -priv (path) {-force}]/[text]```
### Description ###
add an SSL/TLS certificate to a common name given in -name. the common name is used by clients to request certain certificate installed in the host. certificates usually come in seperate cert file and private key file pairs. -cert is the file path to the cert file and -priv is the path to the private key. the files must be formatted in Pem or Der (extension doesn't matter). once installed, the file pairs no longer need to exists for the host to use them. you can the pass the optional -force option to replace a common name if it already exists without asking a confirmation question.

11
docs/intern_commands/add_ch.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
create a new channel.
### IO ###
```[-ch_name (text)]/[text]```
### Description ###
create a new channel with a unique name given in -ch_name. this command will automatically add the currently logged in user as a member and set it as the channel owner. being a channel owner prevents you from being able to delete your account at a later time. you will need to name a new owner from the channel member list or delete the entire channel to allow account deletion. the host will automatically assign a unique channel id for the new channel. channels are used for broadcast peer to peer data transfers within the host and the base channel created by this command is used to manage who has access to such data.

11
docs/intern_commands/add_group.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
create a new host group.
### IO ###
```[-name (text)]/[text]```
### Description ###
this will create a new host group with the unique group name given in -name. all new groups are initialized at rank 2. this can be reconfigured at any time using various group editing commands. host groups are used to manage the access level of all users. each user registered in the host must be assigned a group and each group must be assigned a host rank. the rank is numeric integer that indicates the value of the group's rank. The lower it's numeric value, the higher the level of access the users in that group have in the host with 0 being invalid.

15
docs/intern_commands/add_mod.md Normal file
View File

@ -0,0 +1,15 @@
### Summary ###
upload a new module to install into the host.
### IO ###
```[-client_file (path) -name (text) -len (int)]/[text]```
### Description ###
upload a new module to the host using an archive file (.zip, .tar, .7z, etc...) or a loadable library file (.so, .dll, .a, etc...) using the GEN_FILE data type id. the module name is given in -name while GEN_FILE specific arguments like -len determine the size of the file being sent and -client_file determine the file location on the client's file system. note: the host will use -client_file argument to read the file's suffix and determine if it is an archive or library file.
once successfully unloaded; if it is an archive file, all of it's contents are extracted to the module installation directory. the archive file must contain a loadable library file called 'main' with any of the host platform compatible library suffixes like (.so, .dll, .a, etc...). if a library file is uploaded, it is simply copied over to the module installation directory as 'main.'
if successfully installed, all sessions are notified to load the new module. even after a successful install, the module can still fail to load. check the host debug log for failure details if that is the case.

11
docs/intern_commands/add_ranked_cmd.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
assign a rank to a command object name.
### IO ###
```[-command (text) -rank (int)]/[text]```
### Description ###
this will assign the command rank in -rank to the command name given in -command. assigning ranks to commands give groups that have that rank or higher access to running the command. any commands that don't have an assigned rank is assumed a rank of 1. the lower the numeric value of the rank, the higher the rank (0 is invalid). some commands can claim immunity from host ranking which basically means the command is allowed to load/run regardless of the user's host rank. for internal commands, any commands that edit the user's own information like it's name, display name, password, etc including the login command and various session state commands have immunity.

11
docs/intern_commands/add_rdonly_flag.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
add a read only flag to a certain sub-channel and privilege level.
### IO ###
```[-ch_name (text) -sub_id (int) -level (int)]/[text]```
### Description ###
this adds a read only flag to a sub-channel for users at a certain privilage level given in -level. valid privilage levels range 1-5 representing owner-level(1), admin-level(2), officer-level(3), regular-level(4) and public-level(5). the presents of a read only flag bassically tells the host that users connected to this sub-channel at this level can only receive data from this sub-channel and cannot cast data to the sub-channel. this is useful if you want to setup a channel that allow certain user(s) to broadcast data while everybody else can only listen for the data. the channel name given in -ch_name must already exists but the sub-channel id given in -sub_id doesn't need to exists (valid range 0-255) but what ever sub-channel name that takes the sub-id specified here gets the read only flag. only the channel owner-level(1) and admin-level(2) can add read only flags to sub-channels. also note that this command will cause all sessions that currently have the sub-channel open to close it. it will be up to the clients to re-open the sub-channel.

11
docs/intern_commands/add_sub_ch.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
create a new sub-channel within a channel.
### IO ###
```[-ch_name (text) -sub_name (text)]/[text]```
### Description ###
create a new sub-channel given in -sub_name for the channel given in -ch_name. only the channel owner-level(1) and admin-level(2) is allowed to do this. sub-channels are used to determine which clients can send/receive broadcast data. when a client broadcast data to a open sub-channel, the clients that want to receive that data will also need to have the matching sub-channel open.

11
docs/intern_commands/auth.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
login to the host using a registered user account name or email address.
### IO ###
```[-user (text)] or [-email (text)]/[text]```
### Description ###
login into a user account name given in -user or email address given in -email. this command will ask for the password during execution to complete the authentication.

11
docs/intern_commands/cast.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
broadcast text/data to all sessions listening to any matching sub-channels.
### IO ###
```[any]/[any]```
### Description ###
this sends data passed into it to all peers connected to any of your matching opened sub-channels. this is useful for broadcasting data session-to-session. nothing gets re-sent to the session that initiated the cast.

11
docs/intern_commands/cert_info.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
display detailed information about an installed SSL/TLS certificate.
### IO ###
```[-name (text)]/[text]```
### Description ###
display more detailed information about the SSL/TLS certificate given in -name. -name is the common name clients can use to request a certain certificate installed in the host.

11
docs/intern_commands/ch_owner_override.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
set/unset the channel owner override flag for your current session.
### IO ###
```[-state (1 or 0)]/[text]```
### Description ###
This sets/unsets the channel owner override flag for your current session according to the bool value passed into -state. the owner override flag basically tells the host that the current session can do anything a channel owner can do to any channel in the host and doesn't even need to be a member. this is a simple but very powerful command, it is best reserved for host administrators only.

11
docs/intern_commands/close_host.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
close the host instance.
### IO ###
```[none]/[text]```
### Description ###
this ends all sessions and closes the host main instance. be very careful with this command since it will shutdown the mrci host entirely so all clients will not be able to connect until it is started again.

11
docs/intern_commands/close_sub_ch.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
close a sub-channel for your current session.
### IO ###
```[-ch_name (text) -sub_name (text)]/[text]```
### Description ###
this command closes a sub-channel on your current session so you can stop sending or receiving broadcast data to/from the specific sub-channel name given in -sub_name for the base channel given in -ch_name.

11
docs/intern_commands/cmd_info.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
display detailed information about a command.
### IO ###
```[-cmd_name (text)] or [-cmd_id (int)]/[text]```
### Description ###
display more detailed information about the command name given in -cmd_name or the command id given in -cmd_id.

11
docs/intern_commands/decline_ch.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
decline an invite to a channel.
### IO ###
```[-ch_name (text)]/[text]```
### Description ###
decline or cancel an invite to the channel given in -ch_name. this will fail and do nothing if you do not currently have an existing invite to the channel. the channel owner-level(1), admin-level(2) or officer(3) can also cancel this invite at any time.

11
docs/intern_commands/find_ch.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
search for channels within the host based on the channel name or channel id.
### IO ###
```[-name (text)] or [-id (int)]/[text]```
### Description ###
search the host database for channels with any matching key words given in -name or any channel id given in -id.

11
docs/intern_commands/force_set_email.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
overwrite/change the email address of another user's account.
### IO ###
```[-user (text) -new_email (text)]/[text]```
### Description ###
change the email address for the user account name given in -user to the email adress given in -new_email.

11
docs/intern_commands/fs_cd.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
display or change the current directory for the current session.
### IO ###
```[{-path (text)}]/[text]```
### Description ###
change the current directory of your current session to the directory specified in -path or display it if -path is not specified. note: the current directory is not shared among any of the peer sessions.

11
docs/intern_commands/fs_copy.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
copy a file system object (file,directory,symlink) from one location to another.
### IO ###
```[-src (text) -dst (text) {-force}]/[text]```
### Description ###
copy the file system object (file/directory/symlink) given in -src to the destination given in -dst. this command will ask a confirmation question of the the destination object already exists; pass -force to bypass this. this will also do a full recursive copy if copying a directory.

11
docs/intern_commands/fs_delete.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
attempt to delete a file system object (file,directory,symlink) in the host.
### IO ###
```[-path (text) {-force}]/[text]```
### Description ###
attempt to delete the file system object (file/directory/symlink) given in -path. pass -force to bypass the command's confirmation question. note: this will do a recursive delete if deleting a directory.

17
docs/intern_commands/fs_download.md Normal file
View File

@ -0,0 +1,17 @@
### Summary ###
download a single file from the host.
### IO ###
```[-remote_file (text) {-client_file (text)} {-len (int)} {-offset (int)} {-single_step} {-force} {-truncate}]/[GEN_FILE]```
### Description ###
this command sends GEN_FILE data of the file given in -remote_file. depending on the client, you might need to enter the destination file in -client_file.
-offset is the position in the file to start reading and it defaults to 0 if not given.
-len is the amount of data to read from the file and the host will auto fill it to the file size if not given. the host also auto fill to the file size if it larger than the actual file size.
-single_step enables GEN_FILE's single step mode if the client/host desires it.
-force bypasses any overwrite confirmation question if the client does such a thing.
-truncate tells the client if it should truncate the destination file. the host does nothing with this. it's entirely up to the client to support it.

11
docs/intern_commands/fs_info.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
get detailed information about a file system object (file,directory,symlink) in the host.
### IO ###
```[-path (text) {-info_frame}]/[text] or [FILE_INFO]```
### Description ###
display more information about the file system object (file,directory,symlink) specified in -path. by default, it returns human readable text but the -info_frame option causes the command to return a FILE_INFO frame instead for easier machine parsing.

11
docs/intern_commands/fs_list.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
list all files or sub-directories in a directory.
### IO ###
```[{-path (text)} {-info_frame}]/[text] or [FILE_INFO]```
### Description ###
this list all files in the current directory or the directory specified in -path. this command normally returns human readable text for each file or sub-directory that is listed but you can pass -info_frame to make the command return FILE_INFO frames for each file/sub-directory instead. note: if displaying as text, all directory names are displayed with a '/' at the end.

11
docs/intern_commands/fs_mkpath.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
attempt to create a directory and all sub-directories of a given path.
### IO ###
```[-path (text)]/[text]```
### Description ###
this attempts to create the directory and all sub-directories needed to make the path given in -path. this does nothing if the path already exists.

11
docs/intern_commands/fs_move.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
move/rename a file system object (file,directory,symlink) from one location to another.
### IO ###
```[-src (text) -dst (text) {-force}]/[text]```
### Description ###
move/rename the file system object (file/directory/symlink) given in -src to the destination given in -dst. this command will ask a confirmation question of the the destination file already exists; pass -force to bypass this.

16
docs/intern_commands/fs_upload.md Normal file
View File

@ -0,0 +1,16 @@
### Summary ###
upload a single file to the host.
### IO ###
```[-remote_file (text) -len (int) {-client_file (text)} {-offset (int)} {-single_step} {-force} {-truncate}]/[GEN_FILE]```
### Description ###
attempt to upload the file given in -client_file to the destination file path in the host given in -remote_file. depending on the client, you might not need to enter -len. if supported, the client will auto fill -len with what ever value is needed.
-offset is the position in the file to start writing and it defaults to 0 if not given.
-single_step enables GEN_FILE's single step mode if the client/host desires it.
-force bypasses the overwrite confirmation question if the destination file already exists.
-truncate tells the host if it should truncate the destination file.

11
docs/intern_commands/host_config.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
view/change various host settings.
### IO ###
```[none]/[text]```
### Description ###
view/edit host settings. this command uses a menu system, follow the on screen intructions embedded into the menu.

11
docs/intern_commands/host_info.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
display system information about the host.
### IO ###
```[none]/[text]```
### Description ###
this will display all relevant information about the host.

11
docs/intern_commands/invite_to_ch.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
invite a host user to join a channel.
### IO ###
```[-ch_name (text) -user (text)]/[text]```
### Description ###
invite a new user via the user name given in -user to join the channel given in -ch_name. you must be a member of the channel at any of the following levels for the this to work: owner-level(1), admin-level(2) or officer(3). all new members to any channel are initiated at regular-level(4).

11
docs/intern_commands/is_email_verified.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
check if your email address is verified.
### IO ###
```[none]/[text]```
### Description ###
return a true or false TEXT that indicate if your currently logged in account has a verified email address.

11
docs/intern_commands/lock_acct.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
lock user account.
### IO ###
```[-user (text) -state (0 or 1)]/[text]```
### Description ###
this sets the locked state of a user account name given in -user. locked user accounts are unable to login until the lock is released. -state is a boolean value where 1 is true and 0 is false.

19
docs/intern_commands/ls_act_log.md Normal file
View File

@ -0,0 +1,19 @@
### Summary ###
display or manage the client activity log.
### IO ###
```[{search_terms} {-delete}]/[text]```
### Description ###
by default, all entries in the table are displayed in 50 entries per page. you can pass the column names as -column_name (text) to refine your search to specific entries. this command can handle the following columns:
-time_stamp
-ip_address
-session_id
-client_version
-log_entry
you can also pass -delete that will cause the command to delete the entries instead of displaying them. note: passing no search terms with this option will delete all entries in the table.

25
docs/intern_commands/ls_auth_log.md Normal file
View File

@ -0,0 +1,25 @@
### Summary ###
display or manage the host authorization activity log.
### IO ###
```[{search_terms} {-delete}]/[text]```
### Description ###
by default, all entries in the table are displayed in 50 entries per page. you can pass the column names as -column_name (text) to refine your search to specific entries. this command can handle the following columns:
-time_stamp
-ip_address
-user_name
-auth_attempt
-recover_attempt
-count_to_threshold
-accepted
you can also pass -delete that will cause the command to delete the entries instead of displaying them. note: passing no search terms with this option will delete all entries in the table.
the host use entries in this table to enforce maximum failed login thresholds using a combination of the values found in the -count_to_threshold, -user_name, -count_to_threshold and -accepted columns. so for example, if the host counts a maximum of 50 entries for a certain -user_name with -count_to_threshold = 1 and -accepted = 0 and the host maximum amount of failed attempts is set to 50 then the host will then auto lock the user account to protect it.
the -accepted column is a 1 or 0 to indicate if the user successfully logged in or not and the -count_to_threshold column is also 1 or 0 to determine if this particular entry should be counted toward the threshold or not.

16
docs/intern_commands/ls_bans.md Normal file
View File

@ -0,0 +1,16 @@
### Summary ###
display or manage the host ip address ban table.
### IO ###
```[{search_terms} {-delete}]/[text]```
### Description ###
by default, all entries in the table are displayed in 50 entries per page. you can pass the column names as -column_name (text) to refine your search to specific entries. this command can handle the following columns:
-time_stamp
-ip_address
you can also pass -delete that will cause the command to delete the entries instead of displaying them. note: passing no search terms with this option will delete all entries in the table. keep in mind, the host use this table to enforce the ban-by-ip option. deleting entries in this table will un-ban the ip's affected by the deletion.

11
docs/intern_commands/ls_certs.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
display a list of all SSL/TLS certificates installed in the host database.
### IO ###
```[{search_terms}]/[text]```
### Description ###
by default, all entries in the table are displayed in 50 entries per page. you can pass the column name as -common_name (text) to refine your search to specific entries.

11
docs/intern_commands/ls_ch_members.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
list all members in a channel.
### IO ###
```[-ch_name (text) {-find (text)}]/[text]```
### Description ###
list all members currently in the channel given in -ch_name. you must be a member of the channel (any level) for this to work. this command will display 50 entries per page but you can pass the optional -find argument with a text search term to find members via the user name.

11
docs/intern_commands/ls_chs.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
list all channels you are currently a member of and all pending invites.
### IO ###
```[none]/[text]```
### Description ###
this will list all channels that you are currently a member of including all pending invitations to join other channels. this command will display a maximum of 50 entries per page.

11
docs/intern_commands/ls_cmds.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
list all available commands for your current session.
### IO ###
```[{-find (text)}]/[text]```
### Description ###
display all available commands in your current session in a table format. you can pass an optional -find text to narrow down the size of the list or find specific commands via the command name.

16
docs/intern_commands/ls_dbg.md Normal file
View File

@ -0,0 +1,16 @@
### Summary ###
display debug messages from the host instance and all session instances.
### IO ###
```[{search_terms} {-delete}]/[text]```
### Description ###
by default, all entries in the table are displayed in 50 entries per page. you can pass the column names as -column_name (text) to refine your search to specific entries. this command can handle the following columns:
-time_stamp
-log_entry
you can also pass -delete that will cause the command to delete the entries instead of displaying them. note: passing no search terms with this option will delete all entries in the table.

14
docs/intern_commands/ls_groups.md Normal file
View File

@ -0,0 +1,14 @@
### Summary ###
list all groups currently registered in the host.
### IO ###
```[{search_terms}]/[text]```
### Description ###
by default, all entries in the table are displayed in 50 entries per page. you can pass the column names as -column_name (text) to refine your search to specific entries. this command can handle the following columns:
-group_name
-host_rank

15
docs/intern_commands/ls_mods.md Normal file
View File

@ -0,0 +1,15 @@
### Summary ###
list all available modules currently installed in the host.
### IO ###
```[none]/[text]```
### Description ###
display a list of all modules currently installed in the host. any mods marked with a '1' on the locked column will prevent new sessions from attempting to load it. the presents of a lock can mean 3 things:
1. the module is queued for deletion.
2. installation is in process and the module is not yet ready for loading.
3. a session has crashed while attempting to load the module.

11
docs/intern_commands/ls_open_chs.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
list all of the sub-channels that are currently open.
### IO ###
```[none]/[text]```
### Description ###
this command will list all open sub-channels you are currently listening or broadcasting to.

11
docs/intern_commands/ls_p2p.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
list all p2p connections and pending p2p request you currently have.
### IO ###
```[none]/[text]```
### Description ###
this will list all client session id hashes as hex text that you currently have active connections with or any clients you currently have pending P2P_REQUEST with.

14
docs/intern_commands/ls_ranked_cmds.md Normal file
View File

@ -0,0 +1,14 @@
### Summary ###
list all command names with assigned host ranks.
### IO ###
```[{search_terms}]/[text]```
### Description ###
by default, all entries in the table are displayed in 50 entries per page. you can pass the column names as -column_name (text) to refine your search to specific entries. this command can handle the following columns:
-command_obj_name
-host_rank

11
docs/intern_commands/ls_rdonly_flags.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
list all read only flags currently present for a channel.
### IO ###
```[-ch_name (text)]/[text]```
### Description ###
list all sub-channels with read only flags currently present for the channel name given in -ch_name. non-members of the channel can use this command to list all public sub-channels with read only flags while members of the channel can list all sub-channels with read only flags regardless of access level.

11
docs/intern_commands/ls_sub_chs.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
list all sub-channels within a channel you currently a member of.
### IO ###
```[-ch_name (text)]/[text]```
### Description ###
this will list all sub-channels that currently exists in the channel given in -ch_name. non-members can only list sub-channels accessible to public users while channel members can list all sub-channels regurdless of privilege level.

16
docs/intern_commands/ls_users.md Normal file
View File

@ -0,0 +1,16 @@
### Summary ###
list all users currently registered in the host database.
### IO ###
```[{search_terms}]/[text]```
### Description ###
by default, all entries in the table are displayed in 50 entries per page. you can pass the column names as -column_name (text) to refine your search to specific entries. this command can handle the following columns:
-DateAdded
-UserName
-GroupName
-UserID

11
docs/intern_commands/my_info.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
display information about your current session and your account.
### IO ###
```[none]/[text]```
### Description ###
this displays all available information about the current session and the currently active user account if logged in.

11
docs/intern_commands/open_sub_ch.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
open a sub-channel to send/receive broadcasted data to/from other peers.
### IO ###
```[-ch_name (text) -sub_name (text)]/[text]```
### Description ###
use this command to open the channel and sub-channel name given in -ch for the main channel name and -sub for the sub-channel name. only peers with matching channel-sub combinations can send/receive data with each other when using the cast command. whether peers send/receive auto/pinged PEER_INFO or PEER_STAT frames depends if the active update flag is set on the channel itself or the host.

11
docs/intern_commands/p2p_close.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
close the p2p connection with the client given in this command or decline a p2p request.
### IO ###
```[SESSION_ID]/[none]```
### Description ###
send out a P2P_CLOSE to the client's 28byte (224bit) session id given to this command. this can be used to decline a P2P_REQUEST or close the p2p connection you may have the peer. this command fails if you have no such connection or no pending P2P_REQUEST with the peer.

11
docs/intern_commands/p2p_open.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
accept the p2p request you may have received from another client connected to the host.
### IO ###
```[SESSION_ID]/[none]```
### Description ###
send out a P2P_OPEN to the client's 28byte (224bit) session id given to this command. use this in response to a P2P_REQUEST to accept it. this command fails if you did not receive a P2P_REQUEST from the peer client.

11
docs/intern_commands/p2p_request.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
send out a p2p request to the client session id given in this command.
### IO ###
```[SESSION_ID]/[P2P_CLOSE] or [P2P_OPEN]```
### Description ###
send out a P2P_REQUEST to another client connected to the host. a P2P_OPEN frame will be returned to you from the target session if the request is accepted. you will then be allowed to send any data to/from this peer. a P2P_CLOSE is returned if the request is declined. this command simply takes a 28byte (224bit) hash of the peer client's session id.

11
docs/intern_commands/pause.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
pause the current task that the command is running.
### IO ###
```[{CMD_ID}]/[text]```
### Description ###
this pauses the command given by a CMD_ID frame sent into this command. an error is returned if the requested command is not currently in the looping state. if the frame is empty, this command pauses all commands currently in the looping state.

11
docs/intern_commands/ping_peers.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
ping all peer sessions with any matching sub-channels to return information about themselves to you.
### IO ###
```[none]/[PEER_INFO]```
### Description ###
this will ping all active channels you currently have open. all peer sessions that have any matching open active channels will return a PEER_INFO frame to you.

11
docs/intern_commands/preview_email.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
preview the confirmation or password reset emails with dummy values.
### IO ###
```[-reset_email] or [-confirm_email]/[text]```
### Description ###
preview the reset password email with the -reset_email argument or preview the email confirmation with -confirm_email. this prints the subject first and then the message body with the keywords substituted the dummy values/text.

11
docs/intern_commands/recover_acct.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
reset a user account password.
### IO ###
```[-email (text)] or [-user (text)]/[text]```
### Description ###
reset the password for the user account given in -email or -user. during execution, this command will ask for the temporary password that was sent to that email address when request_pw_reset was called.

11
docs/intern_commands/remove_ch_member.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
remove a user as a member of a channel you currently a member of or cancel an invite.
### IO ###
```[-ch_name (text) -user (text)]/[text]```
### Description ###
remove a user given in -user from the channel member list for the channel given in -ch_name. normally, only the channel owner-level(1), admin-level(2) of officer(3) can do this but it is unrestricted if removing your self as a member except the channel owner. another restriction is if trying to remove members with higher or equal member privileges than your self so officers can't remove admins, other officers or the owner and admins can't remove other admins or the owner. the owner can't be removed from the channel at anytime. this command can also be used to cancel an invite for a user.

11
docs/intern_commands/rename_ch.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
rename a channel.
### IO ###
```[-ch_name (text) -new_name (text)]/[text]```
### Description ###
rename the channel given in -ch_name to the name given in -new_name. valid channel names cannot contain spaces and must be between 4-32 chars long. only the channel owner-level(1) is allowed to do this.

11
docs/intern_commands/rename_sub_ch.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
rename a sub-channel within a channel.
### IO ###
```[-ch_name (text) -sub_name (text) -new_name (text)]/[text]```
### Description ###
rename the sub-channel given in -sub_name for the channel given in -ch_name to the new name given in -new_name. the same rules for channel names also apply to sub-channel names. only the channel owner-level(1) and admin-level(2) is allowed to do this.

11
docs/intern_commands/request_new_pw.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
enable/disable a password change request for a user on next login.
### IO ###
```[-user (text) -req (0 or 1)]/[text]```
### Description ###
this will set or unset the request for the user given in -user to change the password on next login. pass 0 on -req to disable the request or pass 1 to enable the request. the request is automatically disabled when the user successfully changes the password.

11
docs/intern_commands/request_new_user_name.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
enable/disable a user name change request for a user on next login.
### IO ###
```[-user (text) -req (0 or 1)]/[text]```
### Description ###
this will set or unset the request for the user given in -user to change the user name on next login. pass 0 on -req to disable the request or pass 1 to enable the request. the request is automatically disabled when the user successfully changes the user name.

11
docs/intern_commands/request_pw_reset.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
request a password reset for a user account.
### IO ###
```[-email (text)] or [-user (text)]/[text]```
### Description ###
this will send a temporary password for the user account associated with the email adress given in -email or the username given in -user. this password can then be used with recover_account to reset the password.

11
docs/intern_commands/restart_host.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
re-start the host instance.
### IO ###
```[none]/[text]```
### Description ###
this will restart the host instance, along with a database reload. be very careful with this command. it ends all current sessions and since it also reloads the database, host behaviour might also change depending on what is in the new database if the path was changed.

11
docs/intern_commands/resume.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
resumes the current task that the command is running.
### IO ###
```[{CMD_ID}]/[text]```
### Description ###
this resumes the looping task for the command given by a CMD_ID frame sent into this command. a failure is returned if the command is not currently in a paused state. if the frame is empty, all currently paused commands are resumed.

11
docs/intern_commands/rm_acct.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
delete a user account from the host database.
### IO ###
```[-name (text) {-force}]/[text]```
### Description ###
delete the user account given in -name. this will also automatically kill all sessions currently using this user account. be very careful with this command since it's changes cannot be undone. you can use the -force option to bypass the confirmation question.

11
docs/intern_commands/rm_ban.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
remove an ip address from the ban list.
### IO ###
```[-ip (text)]/[text]```
### Description ###
this removes an ip address from the host ban list. nothing happens if the ip does not exists in the list.

11
docs/intern_commands/rm_cert.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
remove the SSL/TLS cert associated with the given common name.
### IO ###
```[-name (text) {-force}]/[text]```
### Description ###
remove the SSL/TLS certificate and private key for the common name given in -name. you can the pass the optional -force option to remove the cert without asking a confirmation question.

11
docs/intern_commands/rm_ch.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
permanently remove a channel and all of it's sub-shannels from the host.
### IO ###
```[-ch_name (text)]/[text]```
### Description ###
this will permanently remove the channel given in -ch_name and all sub-channels. only the channel owner-level(1) is allowed to do this.

11
docs/intern_commands/rm_mod.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
uninstall a module from the host.
### IO ###
```[-name (text)]/[text]```
### Description ###
this tells all sessions in the host to unload the module given in -name and all associated commands. it will also permanently delete all files associated with the module from the host. file deletion is not done instantly; instead, a specific amount of time is allotted to allow all sessions to unload the mod/clean up before it's files are deleted. also note that all associated commands are forced to terminate when the module is unloaded.

11
docs/intern_commands/rm_ranked_cmd.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
remove a rank from a command object name.
### IO ###
```[-command (text)]/[text]```
### Description ###
this will remove the command rank from the command object given in -command. any command object without an assigned perm id is assumed a rank of 1 but some exceptions apply for commands that need to be allowed for all users regardless of rank.

11
docs/intern_commands/rm_rdonly_flag.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
remove a read only flag from a certain sub-channel privilege level combination.
### IO ###
```[-ch_name (text) -sub_id (int) -level (int)]/[text]```
### Description ###
remove a read only flag the sub-channel given in -sub_id for connected users at the level given in -level. the channel given in -ch_name must already exists. with, the read only flag gone users connected to the sub-channel at the specified level would be able to cast data to the sub-channel once again. also note that this command will cause all sessions that currently have the sub-channel open to close the sub-channel. it will be up to the clients to re-open the sub-channel.

11
docs/intern_commands/rm_sub_ch.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
remove a sub-channel within a channel.
### IO ###
```[-ch_name (text) -sub_name (text)]/[text]```
### Description ###
remove a sub-channel given in -sub_name for the channel given in -ch_name. only the channel owner-level(1) and admin-level(2) is allowed to do this. only the channel owner-level(1) and admin-level(2) is allowed to do this.

11
docs/intern_commands/set_active_flag.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
set or unset the active update flag of a sub-channel.
### IO ###
```[-ch_name (text) -sub_name (text) -state (1 or 0)]/[text]```
### Description ###
this sets the active update flag on the channel given in -ch_name true or false based on the value given in -state. the active update flag allow the sessions to send PEER_INFO or PEER_STAT frames to the clients when a peer connected to the channel changes information like it's user name, group name, display name, disconnect etc...this flag is ignored if the host have the global active update flag set. if that's the case, all channels will active update. the channel owner-level(1) and admin-level(2) is allowed to do this.

11
docs/intern_commands/set_disp_name.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
change your account display name.
### IO ###
```[-name (text)]/[text]```
### Description ###
this changes the display name on your own account to the name given in -name. the display name is used by some clients to present your account to other clients instead of showing your real user name. it is not restricted by uniqueness and can be any text that is less than or equal to 32 chars.

11
docs/intern_commands/set_email.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
change the user account email address.
### IO ###
```[-new_email (text)]/[text]```
### Description ###
change the email address on your own account to the email adress given in -new_email.

22
docs/intern_commands/set_email_template.md Normal file
View File

@ -0,0 +1,22 @@
### Summary ###
set the email template used by the host to send emails for user account resets and confirmations.
### IO ###
```[[-reset_template] or [-confirm_template] {-subject {(text)}} {[-body {(text)}] or [-client_file (text) -len (int)]}]/[text]```
### Description ###
this updates the email template used by the host to send emails to the users that request password resets and or email confirmations. the presents of -reset_template updates the password reset email or the presents of -confirm_template updates the confirmation email. -subject is exactly as the name implies, it tells the host what subject to use when sending the email.
-body sets the email message body directly from the command line or -client_file loads the body from a text file. if uploading a text file, use the -len parameter to enter the file size in bytes if your client does not auto fill that.
the message body must contain the following keywords to be acceptable:
%user_name%
%date%
%temp_pw% (if -reset_template)
%confirmation_code% (if -confirm_template)
the host will substitute these keywords with actual values/text when contructing the email. note: if sending a text file, the host assumes it is encoded in UTF-16LE. pass an empty -subject and/or a empty -body to reset the values to host defaults. if the body or subject contains single quotes ' ' escape them with a \.

11
docs/intern_commands/set_group.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
change a user account's group.
### IO ###
```[-user (text) -group (text)]/[text]```
### Description ###
this changes the group of the user account given in -user to the target group given in -group.

11
docs/intern_commands/set_group_rank.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
set the host rank of a group.
### IO ###
```[-name (text) -rank (int)]/[text]```
### Description ###
set the host rank for the group name given in -name to the rank given in -rank. the host rank is used throughout this application to determine how much access to the host commands each user attached to the group has. the lower the numeric value of the host rank, the higher the level of access to the host the group has (1 being the highest level of access). you cannot change the group of a group that has a higher rank than your own group.

41
docs/intern_commands/set_member_level.md Normal file
View File

@ -0,0 +1,41 @@
### Summary ###
set the user privilege levels of a channel member. (lower the value, the higher the privilege)
### IO ###
```[-ch_name (text) -user (text) -level (int)]/[text]```
### Description ###
set the privilege level of the channel member given in -user for the channel given in -ch_name to the level given in -level. a valid privilege level is an integer between 1-4 representing owner-level(1), admin-level(2), officer-level(3) and regular-level(4). the channel owner-level(1) is reserved for just 1 member in the channel and only that member can assign another member in the channel that privilege level. when the owner privilege is assigned to another member, the current owner will step down to a admin. this command is restricted based on your current level so you cannot assign a level higher that you own. below is a description of what each of these levels can do within the channel:
owner-level(1):
1. delete or rename the channel.
2. delete, create or rename sub-channels within the channel.
3. invite new users to the channel or cancel invites.
4. remove any member of the channel except your self.
5. set sub-channels' level of access.
6. add/remove read only flags to/from sub-channels.
7. update the privilege level of any member in the channel.
8. open/close sub-channels for casting.
admin-level(2):
1. delete, create or rename sub-channels within the channel.
2. invite new users to the channel or cancel invites.
3. remove any member of channel except the owner and other admins.
4. set sub-channels' level of access.
5. add/remove read only flags to/from sub-channels.
6. update the privilege level of members up to your own level but not above.
7. open/close sub-channels for casting.
officer-level(3):
1. invite new users to the channel or cancel invites.
2. can only remove regular members of the channel.
3. update the privilege level of members up to your own level but not above.
4. open/close sub-channels for casting.
regular-level(4):
1. open/close sub-channels for casting.
note: this command causes all sessions that are loggined in as this user to close all related sub-channels. it will be up to the client to re-open the sub-channels if the user still have access to them.

11
docs/intern_commands/set_pw.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
change your account password.
### IO ###
```[password]/[text]```
### Description ###
this changes the password on your own account. this command will instantly hook the input and await a new password to be entered.

11
docs/intern_commands/set_sub_ch_level.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
set the lowest privilege level that members need to be in order to open a certain sub-channel.
### IO ###
```[-ch_name (text) -sub_name (text) -level (int)]/[text]```
### Description ###
this command makes it possible so set minimum privilege levels to open the sub-channel given in -sub_name to the level given in -level for the channel given in -ch_name. a valid level is an integer between 1-5 representing owner-level(1), admin-level(2), officer-level(3), regular-level(4) and public-level(5). for example, you could set a sub-channel's minimum level to 4 to make it so only channel regular members and above can open/close the sub-channel or you can set it to 5 to make it so anybody can open/close the sub-channel, affectively making it a public sub-channel. only the channel owner or admin(s) are allowed to do this. also note that this command will cause all sessions that currently have the sub-channel open to close the sub-channel. it will be up to the client to re-open the sub-channel if it's user account still have access to it.

11
docs/intern_commands/set_user_name.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
change your account user name.
### IO ###
```[-new_name (text)]/[text]```
### Description ###
this changes the user name on your own account to the new user name given in -new_name.

11
docs/intern_commands/term.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
terminate the current task that the command is running.
### IO ###
```[{CMD_ID}]/[text]```
### Description ###
this terminates the command given by a CMD_ID frame sent into this command. if the frame is empty, this command terminates all commands. this command doesn't care if the target command object itself is in looping and/or more input states.

11
docs/intern_commands/to_peer.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
send/receive any data directly with a client connected to the host that has accepted your p2p request or the peer's p2p request.
### IO ###
```[(SESSION_ID)any]/[none]```
### Description ###
send any type of data directly to a peer client connected to the host that has accepted your p2p request. you must prepend the data sent into this command with the 224bit hash the peer's session id. an error is called out if the peer session has not accepted your p2p request.

11
docs/intern_commands/trans_group.md Normal file
View File

@ -0,0 +1,11 @@
### Summary ###
transfer all user accounts from one group to another.
### IO ###
```[-src (text) -dst (text)]/[text]```
### Description ###
transfer all user accounts currently attached to the group given in -src to the group given in -dst. you must have a higher rank than both groups for this to work.

Some files were not shown because too many files have changed in this diff Show More