zii/MRCI
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
80d493ad16
MRCI/docs/README.md

111 lines
5.8 KiB
Markdown
Raw Normal View History

Initial commit for the MRCI project.
2019-09-06 23:43:07 -04:00
# MRCI #
Further updated the documentation and a minor fix fixed some errors found in the documentation and fully updated the internal commands docs as well. also updated the internal module to now respond to KILL_CMD so it can now be signaled to terminate gracefully.
2019-11-18 19:20:30 -05:00
(Modular Remote Command Interpreter) is a command interpreter primarily designed to provide any type of remote service to connected clients. 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 users. All persistent data is handled by a SQLite database and all remote connections are handled via TCP and encrypted in SSL/TLS.
Initial commit for the MRCI project.
2019-09-06 23:43:07 -04:00
### Usage ###
```
<Arguments>
Full documentation update and minor changes -the add_mod command now requires the -mod_path argument as it should. -the session now filter out bad NEW_CMD frames based on bad command names and incorrect frame sizes. -modules running in list mode can now send ERR frames to the session to log error messages to the host database.
2019-11-16 13:08:02 -05:00
Few Updates to SSL Cert Handling - SSL certs are no longer stored in the host database. This was done not only for security reasons but there is simply no need to do such thing anymore. - The host will longer support multiple SSL certs and will instead have just a single cert for all TCP connections. This required a change to the client header format that simply replaced the the common name with padding. The host will also no longer send the HOST_CERT type id during session initialization. HOST_CERT was also removed as a type id. - The cert and privite key are now pointed to files in the local file system by the environment variables: MRCI_PRIV_KEY and MRCI_PUB_KEY. - The host will still create a default self-signed cert if a valid cert and private key is not defined in the above environmental vars. Since the host only support single certs now, the default cert needed to be expanded to include subject alternative names. The host will try to detect it's WAN ip address using ipify.org and then assign SANs for all detected local LAN interfaces. - Since the cert is now handled by environmental vars and nothing related to it stored in the database, all the core commands related to cert management were removed.
2020-04-05 15:51:11 -04:00
-help : display usage information about this application.
-stop : stop the current host instance if one is currently running.
-about : display versioning/warranty information about this application.
-addr : 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 the default password.
-host : start a new host instance. (this blocks)
-default_pw : show the default password.
-public_cmds : run the internal module to list it's public commands. for internal use only.
-exempt_cmds : run the internal module to list it's rank exempt commands. for internal use only.
-user_cmds : run the internal module to list it's user commands. for internal use only.
-run_cmd : run an internal module command. for internal use only.
-add_cert : add/update an SSL certificate for a given common name.
-rm_cert : remove an SSL certificate for a given common name.
Full documentation update and minor changes -the add_mod command now requires the -mod_path argument as it should. -the session now filter out bad NEW_CMD frames based on bad command names and incorrect frame sizes. -modules running in list mode can now send ERR frames to the session to log error messages to the host database.
2019-11-16 13:08:02 -05:00
Internal module | -public_cmds, -user_cmds, -exempt_cmds, -run_cmd |:
Few Updates to SSL Cert Handling - SSL certs are no longer stored in the host database. This was done not only for security reasons but there is simply no need to do such thing anymore. - The host will longer support multiple SSL certs and will instead have just a single cert for all TCP connections. This required a change to the client header format that simply replaced the the common name with padding. The host will also no longer send the HOST_CERT type id during session initialization. HOST_CERT was also removed as a type id. - The cert and privite key are now pointed to files in the local file system by the environment variables: MRCI_PRIV_KEY and MRCI_PUB_KEY. - The host will still create a default self-signed cert if a valid cert and private key is not defined in the above environmental vars. Since the host only support single certs now, the default cert needed to be expanded to include subject alternative names. The host will try to detect it's WAN ip address using ipify.org and then assign SANs for all detected local LAN interfaces. - Since the cert is now handled by environmental vars and nothing related to it stored in the database, all the core commands related to cert management were removed.
2020-04-05 15:51:11 -04:00
-pipe : the named pipe used to establish a data connection with the session.
-mem_ses : the shared memory key for the session.
-mem_host : the shared memory key for the host main process.
Details:
addr - this argument takes a {ip_address:port} string. it will return an error if not formatted correctly
examples: 10.102.9.2:35516 or 0.0.0.0:35516.
run_cmd - this argument is used by the host itself, along side the internal module arguments below to run
the internal command names passed by it. this is not ment to be run directly by human input.
the executable will auto close if it fails to connect to the pipe and/or shared memory segments
Initial commit for the MRCI project.
2019-09-06 23:43:07 -04:00
```
Further updated the documentation and a minor fix fixed some errors found in the documentation and fully updated the internal commands docs as well. also updated the internal module to now respond to KILL_CMD so it can now be signaled to terminate gracefully.
2019-11-18 19:20:30 -05:00
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 0.0.0.0 and port 35516, effectively making it reachable on any network interface of the host platform via that specific port.
Full documentation update and minor changes -the add_mod command now requires the -mod_path argument as it should. -the session now filter out bad NEW_CMD frames based on bad command names and incorrect frame sizes. -modules running in list mode can now send ERR frames to the session to log error messages to the host database.
2019-11-16 13:08:02 -05:00
Password and account security updates security updates: various commands that change or create account passwords now disallow the user name, display name or email from being contained in it. this will force users to not use public information inside the password, hardening password security a little. the root user name is now changeable and required to be changed on initial login. this harden security a little by giving host admins the option to not have a well known user name attached to a high privileged account. users can no longer re-use the old password and/or user name when required to change. however, this does not actually implement full password history because the user can then later change the password back to the old password after the required change. the host can longer block by ip addresses and the auto block threshold setting has been removed. something like this is best left up to firewalls, routers, switches or any other networking infrastructure. in the future i can consider adding event triggering that run certain admin defined external or internal commands when the host detects certain event thresholds. minor changes/bug fixes: all commands that change or create user names now no longer accept user names that looks like an mail address. this works out better for clients when differentiating logging in via user name or email address. the recover_acct command now also have cancel on blank text options making it more consistent with all other commands that take text input. resetting the root user's account password via command line now also unlocks it if locked. the -help and -about command line options no longer display the default password. a new -default_pw option was added for this purpose. the -status -addr or -stop command line options require super user privileges to run properly depending on how the host is installed. an error message like "permission denied" was addded on failure to make this requirement clear to the end user. fs_copy and fs_move now does implicit skip on error instead of stop on error. the IDLE frame type id now carry an integer return code that can be interpreted by clients to determine the result of the command that was sent to the host. house keeping: all documentation was updated to reflect the changes made in this commit. the module tester example is no longer relevant to this project so it was deleted.
2020-01-29 12:29:01 -05:00
Any one user account registered with the host can be given root privileges which basically gives this user unrestricted access to anything in the host for administrative purposes. When a host instance is created for the first time, it will create a new user account called 'root' with a randomized default password. To find out what the default password is, run -default_pw. When logging in for the fist time, the host will require you to change the user name and password before continuing.
Initial commit for the MRCI project.
2019-09-06 23:43:07 -04:00
### 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.
Full documentation update and minor changes -the add_mod command now requires the -mod_path argument as it should. -the session now filter out bad NEW_CMD frames based on bad command names and incorrect frame sizes. -modules running in list mode can now send ERR frames to the session to log error messages to the host database.
2019-11-16 13:08:02 -05:00
* Fully feasured user account management system.
Initial commit for the MRCI project.
2019-09-06 23:43:07 -04:00
* 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 ###
Full documentation update and minor changes -the add_mod command now requires the -mod_path argument as it should. -the session now filter out bad NEW_CMD frames based on bad command names and incorrect frame sizes. -modules running in list mode can now send ERR frames to the session to log error messages to the host database.
2019-11-16 13:08:02 -05:00
* [1.1 The Protocol](protocol.md)
* [2.1 Modules](modules.md)
* [3.1 Type IDs](type_ids.md)
* [4.1 Host Features](host_features.md)
* [5.1 Async Commands](async.md)
* [6.1 Shared Memory](shared_data.md)
Further updated the documentation and a minor fix fixed some errors found in the documentation and fully updated the internal commands docs as well. also updated the internal module to now respond to KILL_CMD so it can now be signaled to terminate gracefully.
2019-11-18 19:20:30 -05:00
* [7.1 Internal Commands](intern_commands.md)
Initial commit for the MRCI project.
2019-09-06 23:43:07 -04:00
### 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.
Updated the documentation Updated all documentation related to the changes made in the previous commit.
2019-09-26 22:00:51 -04:00
2. Path of the output makeself file (usually has a .run extension). If not given, the outfile will be named mrci-x.x.x.run in the source code folder.
Initial commit for the MRCI project.
2019-09-06 23:43:07 -04:00
Build:
```
cd /path/to/source/code
sh ./linux_build.sh
```
Install:
```
Updated the documentation Updated all documentation related to the changes made in the previous commit.
2019-09-26 22:00:51 -04:00
chmod +x ./mrci-x.x.x.run
./mrci-x.x.x.run
Initial commit for the MRCI project.
2019-09-06 23:43:07 -04:00
```
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:
```
Update README.md the host no longer uses the user specification '@' symbol with systemd so the README file was updated to reflect this change.
2019-12-24 16:04:22 -05:00
sudo systemctl start mrci
sudo systemctl stop mrci
Initial commit for the MRCI project.
2019-09-06 23:43:07 -04:00
```
Reference in New Issue Copy Permalink