zii/Cmdr
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
347e01eeff
Cmdr/docs/README.md

121 lines
6.5 KiB
Markdown
Raw Normal View History

Initial commit for the Cmdr project.
2019-09-14 13:03:34 -04:00
# Cmdr #
Versioning system change and support of new MRCI host features added support for the new PROMPT_TEXT data type id. it is simply treated like any other TEXT type for this application. added a hiddden progress bar below the main text body that will only kick in when it detects a string of the PROG/PROG_LAST data types. refactored "halt" to "yield" on the client's internal command. also refactored "text_settings" to "theme" on the json config file. the config file name will now also include the major version number as a way to verify compatibility as the client is updated. changed the client's versioning system to a 2 number system. more info about this new system was edited into the README.md file. synced the type_id and async_id values with MRCI host. added support for the new MRCI host 4 number versioning system. this client will only care about the tcp_rev part of this new system for now. any changes to the hosts' core commands shouldn't affect compatibility with this client.
2020-03-10 19:04:48 -04:00
Cmdr is a command line terminal emulator client for MRCI host using text input/output. This help administer MRCI host via local or remote TCP connections encrypted with TLS/SSL using the MRCI protocol. It also supports file transfers to/from the client using the GEN_FILE sub-protocol that MRCI understands.
Initial commit for the Cmdr project.
2019-09-14 13:03:34 -04:00
### Usage ###
Major upgrade and changes the MRCI protocol has been upgraded to support branch ids so running multiple instances of the same command can run at the same time at the host side. this client however will still continue to run host commands in FIFO but this is something that can be added in the near future. another change to the protocol is the version negotiation is now entirely one-sided so just the client can now decide of the host version is acceptable or not. the NEW_CMD frames from MRCI host will now include all of the command documentation so listing of all available commands and documentation is now entirely client controlled because the host no longer have built in documentation commands. this client's Session object now operate in it's own thread. for now, this does nothing but this is a prelude for future performance updates that will including multi-threading.
2019-11-23 14:37:41 -05:00
Cmdr have it's own terminal display so there is no command line switches to pass on start up. Instead, all commands are parsed and processed within it's own terminal interface. Any commands not seen as an internal command for the client itself is passed through to the MRCI host if connected. The client will add a numeric identifer to the end of all host command names that clash with the client commands so there is no chance a client and host command can conflict with each other.
Initial commit for the Cmdr project.
2019-09-14 13:03:34 -04:00
### Versioning System ###
Versioning system change and support of new MRCI host features added support for the new PROMPT_TEXT data type id. it is simply treated like any other TEXT type for this application. added a hiddden progress bar below the main text body that will only kick in when it detects a string of the PROG/PROG_LAST data types. refactored "halt" to "yield" on the client's internal command. also refactored "text_settings" to "theme" on the json config file. the config file name will now also include the major version number as a way to verify compatibility as the client is updated. changed the client's versioning system to a 2 number system. more info about this new system was edited into the README.md file. synced the type_id and async_id values with MRCI host. added support for the new MRCI host 4 number versioning system. this client will only care about the tcp_rev part of this new system for now. any changes to the hosts' core commands shouldn't affect compatibility with this client.
2020-03-10 19:04:48 -04:00
This application uses a 2 number versioning system: [major].[minor]
Initial commit for the Cmdr project.
2019-09-14 13:03:34 -04:00
Versioning system change and support of new MRCI host features added support for the new PROMPT_TEXT data type id. it is simply treated like any other TEXT type for this application. added a hiddden progress bar below the main text body that will only kick in when it detects a string of the PROG/PROG_LAST data types. refactored "halt" to "yield" on the client's internal command. also refactored "text_settings" to "theme" on the json config file. the config file name will now also include the major version number as a way to verify compatibility as the client is updated. changed the client's versioning system to a 2 number system. more info about this new system was edited into the README.md file. synced the type_id and async_id values with MRCI host. added support for the new MRCI host 4 number versioning system. this client will only care about the tcp_rev part of this new system for now. any changes to the hosts' core commands shouldn't affect compatibility with this client.
2020-03-10 19:04:48 -04:00
* Major - this indicates any changes that cause old configuration or library files to be incompatible.
* Minor - this indicates changes to the code that still maintains compatibility with existing config files or libraries.
Initial commit for the Cmdr project.
2019-09-14 13:03:34 -04:00
Versioning system change and support of new MRCI host features added support for the new PROMPT_TEXT data type id. it is simply treated like any other TEXT type for this application. added a hiddden progress bar below the main text body that will only kick in when it detects a string of the PROG/PROG_LAST data types. refactored "halt" to "yield" on the client's internal command. also refactored "text_settings" to "theme" on the json config file. the config file name will now also include the major version number as a way to verify compatibility as the client is updated. changed the client's versioning system to a 2 number system. more info about this new system was edited into the README.md file. synced the type_id and async_id values with MRCI host. added support for the new MRCI host 4 number versioning system. this client will only care about the tcp_rev part of this new system for now. any changes to the hosts' core commands shouldn't affect compatibility with this client.
2020-03-10 19:04:48 -04:00
Any increments to major resets minor to 0.
Initial commit for the Cmdr project.
2019-09-14 13:03:34 -04:00
### The Protocol ###
Major upgrade and changes the MRCI protocol has been upgraded to support branch ids so running multiple instances of the same command can run at the same time at the host side. this client however will still continue to run host commands in FIFO but this is something that can be added in the near future. another change to the protocol is the version negotiation is now entirely one-sided so just the client can now decide of the host version is acceptable or not. the NEW_CMD frames from MRCI host will now include all of the command documentation so listing of all available commands and documentation is now entirely client controlled because the host no longer have built in documentation commands. this client's Session object now operate in it's own thread. for now, this does nothing but this is a prelude for future performance updates that will including multi-threading.
2019-11-23 14:37:41 -05:00
This application being a MRCI client uses the MRCI protocol to transport data to and from the host using TCP in a binary data format called MRCI frames. In general, local connections with the host are not encrypted but all connections outside of the host must be encrypted using TLS/SSL (including the local network).
Initial commit for the Cmdr project.
2019-09-14 13:03:34 -04:00
Major upgrade and changes the MRCI protocol has been upgraded to support branch ids so running multiple instances of the same command can run at the same time at the host side. this client however will still continue to run host commands in FIFO but this is something that can be added in the near future. another change to the protocol is the version negotiation is now entirely one-sided so just the client can now decide of the host version is acceptable or not. the NEW_CMD frames from MRCI host will now include all of the command documentation so listing of all available commands and documentation is now entirely client controlled because the host no longer have built in documentation commands. this client's Session object now operate in it's own thread. for now, this does nothing but this is a prelude for future performance updates that will including multi-threading.
2019-11-23 14:37:41 -05:00
Before any MRCI frames can be transported, both the host and client need basic information about each other. 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, described below.
Initial commit for the Cmdr project.
2019-09-14 13:03:34 -04:00
### MRCI Frame Format ###
```
Major upgrade and changes the MRCI protocol has been upgraded to support branch ids so running multiple instances of the same command can run at the same time at the host side. this client however will still continue to run host commands in FIFO but this is something that can be added in the near future. another change to the protocol is the version negotiation is now entirely one-sided so just the client can now decide of the host version is acceptable or not. the NEW_CMD frames from MRCI host will now include all of the command documentation so listing of all available commands and documentation is now entirely client controlled because the host no longer have built in documentation commands. this client's Session object now operate in it's own thread. for now, this does nothing but this is a prelude for future performance updates that will including multi-threading.
2019-11-23 14:37:41 -05:00
[type_id][cmd_id][branch_id][data_len][payload]
Initial commit for the Cmdr project.
2019-09-14 13:03:34 -04:00
Major upgrade and changes the MRCI protocol has been upgraded to support branch ids so running multiple instances of the same command can run at the same time at the host side. this client however will still continue to run host commands in FIFO but this is something that can be added in the near future. another change to the protocol is the version negotiation is now entirely one-sided so just the client can now decide of the host version is acceptable or not. the NEW_CMD frames from MRCI host will now include all of the command documentation so listing of all available commands and documentation is now entirely client controlled because the host no longer have built in documentation commands. this client's Session object now operate in it's own thread. for now, this does nothing but this is a prelude for future performance updates that will including multi-threading.
2019-11-23 14:37:41 -05:00
type_id - 1byte - 8bit little endian integer type id of the payload.
cmd_id - 2bytes - 16bit little endian integer command id.
branch_id - 2bytes - 16bit little endian integer branch id.
data_len - 3bytes - 24bit little endian integer size of the payload.
payload - variable - the actual data to be processed.
Initial commit for the Cmdr project.
2019-09-14 13:03:34 -04:00
```
Major upgrade and changes the MRCI protocol has been upgraded to support branch ids so running multiple instances of the same command can run at the same time at the host side. this client however will still continue to run host commands in FIFO but this is something that can be added in the near future. another change to the protocol is the version negotiation is now entirely one-sided so just the client can now decide of the host version is acceptable or not. the NEW_CMD frames from MRCI host will now include all of the command documentation so listing of all available commands and documentation is now entirely client controlled because the host no longer have built in documentation commands. this client's Session object now operate in it's own thread. for now, this does nothing but this is a prelude for future performance updates that will including multi-threading.
2019-11-23 14:37:41 -05:00
notes:
* A full description of the type id's can be found in the [Type_IDs.md](type_ids.md) document.
* This client call commands by name but the host will assign unique command ids for it's command names and will require the client to use the command id on calling. To track this command id to command name relationship for the host commands, this client will rely on the [ASYNC_ADD_CMD](async.md) and [ASYNC_RM_CMD](async.md) async commands.
* The branch id is an id that can be used to run muliple instances of the same command on the host. Commands sent by a certain branch id will result in data sent back with that same branch id. For now, this client does not do branching; instead all commands sent to the host using branch id 0 only.
Initial commit for the Cmdr project.
2019-09-14 13:03:34 -04:00
### Client Header (This Application) ###
```
Major upgrade and changes the MRCI protocol has been upgraded to support branch ids so running multiple instances of the same command can run at the same time at the host side. this client however will still continue to run host commands in FIFO but this is something that can be added in the near future. another change to the protocol is the version negotiation is now entirely one-sided so just the client can now decide of the host version is acceptable or not. the NEW_CMD frames from MRCI host will now include all of the command documentation so listing of all available commands and documentation is now entirely client controlled because the host no longer have built in documentation commands. this client's Session object now operate in it's own thread. for now, this does nothing but this is a prelude for future performance updates that will including multi-threading.
2019-11-23 14:37:41 -05:00
[tag][appName][coName]
Initial commit for the Cmdr project.
2019-09-14 13:03:34 -04:00
tag - 4bytes - 0x4D, 0x52, 0x43, 0x49 (MRCI)
Major upgrade and changes the MRCI protocol has been upgraded to support branch ids so running multiple instances of the same command can run at the same time at the host side. this client however will still continue to run host commands in FIFO but this is something that can be added in the near future. another change to the protocol is the version negotiation is now entirely one-sided so just the client can now decide of the host version is acceptable or not. the NEW_CMD frames from MRCI host will now include all of the command documentation so listing of all available commands and documentation is now entirely client controlled because the host no longer have built in documentation commands. this client's Session object now operate in it's own thread. for now, this does nothing but this is a prelude for future performance updates that will including multi-threading.
2019-11-23 14:37:41 -05:00
appName - 134bytes - UTF16LE string (padded with 0x00)
coName - 272bytes - UTF16LE string (padded with 0x00)
Initial commit for the Cmdr project.
2019-09-14 13:03:34 -04:00
```
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.
Versioning system change and support of new MRCI host features added support for the new PROMPT_TEXT data type id. it is simply treated like any other TEXT type for this application. added a hiddden progress bar below the main text body that will only kick in when it detects a string of the PROG/PROG_LAST data types. refactored "halt" to "yield" on the client's internal command. also refactored "text_settings" to "theme" on the json config file. the config file name will now also include the major version number as a way to verify compatibility as the client is updated. changed the client's versioning system to a 2 number system. more info about this new system was edited into the README.md file. synced the type_id and async_id values with MRCI host. added support for the new MRCI host 4 number versioning system. this client will only care about the tcp_rev part of this new system for now. any changes to the hosts' core commands shouldn't affect compatibility with this client.
2020-03-10 19:04:48 -04:00
* 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. If the client doesn't know which cert to request, it is good practice to use the address that was used to connect to the host.
Initial commit for the Cmdr project.
2019-09-14 13:03:34 -04:00
### Host Header ###
```
Format:
Versioning system change and support of new MRCI host features added support for the new PROMPT_TEXT data type id. it is simply treated like any other TEXT type for this application. added a hiddden progress bar below the main text body that will only kick in when it detects a string of the PROG/PROG_LAST data types. refactored "halt" to "yield" on the client's internal command. also refactored "text_settings" to "theme" on the json config file. the config file name will now also include the major version number as a way to verify compatibility as the client is updated. changed the client's versioning system to a 2 number system. more info about this new system was edited into the README.md file. synced the type_id and async_id values with MRCI host. added support for the new MRCI host 4 number versioning system. this client will only care about the tcp_rev part of this new system for now. any changes to the hosts' core commands shouldn't affect compatibility with this client.
2020-03-10 19:04:48 -04:00
[reply][major][minor][tcp_rev][mod_rev][sesId]
Initial commit for the Cmdr project.
2019-09-14 13:03:34 -04:00
Versioning system change and support of new MRCI host features added support for the new PROMPT_TEXT data type id. it is simply treated like any other TEXT type for this application. added a hiddden progress bar below the main text body that will only kick in when it detects a string of the PROG/PROG_LAST data types. refactored "halt" to "yield" on the client's internal command. also refactored "text_settings" to "theme" on the json config file. the config file name will now also include the major version number as a way to verify compatibility as the client is updated. changed the client's versioning system to a 2 number system. more info about this new system was edited into the README.md file. synced the type_id and async_id values with MRCI host. added support for the new MRCI host 4 number versioning system. this client will only care about the tcp_rev part of this new system for now. any changes to the hosts' core commands shouldn't affect compatibility with this client.
2020-03-10 19:04:48 -04:00
reply - 1byte - 8bit little endian unsigned int
major - 2bytes - 16bit little endian unsigned int
minor - 2bytes - 16bit little endian unsigned int
tcp_rev - 2bytes - 16bit little endian unsigned int
mod_rev - 2bytes - 16bit little endian unsigned int
sesId - 28bytes - 224bit sha3 hash
Initial commit for the Cmdr project.
2019-09-14 13:03:34 -04:00
```
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.
Major upgrade and changes the MRCI protocol has been upgraded to support branch ids so running multiple instances of the same command can run at the same time at the host side. this client however will still continue to run host commands in FIFO but this is something that can be added in the near future. another change to the protocol is the version negotiation is now entirely one-sided so just the client can now decide of the host version is acceptable or not. the NEW_CMD frames from MRCI host will now include all of the command documentation so listing of all available commands and documentation is now entirely client controlled because the host no longer have built in documentation commands. this client's Session object now operate in it's own thread. for now, this does nothing but this is a prelude for future performance updates that will including multi-threading.
2019-11-23 14:37:41 -05:00
* reply = 1, means the client is acceptable and it does not need to take any further action.
* reply = 2, means the client 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 = 4, means the host was unable to find the SSL cert associated with the common name sent by the client. The session will auto close at this point.
Versioning system change and support of new MRCI host features added support for the new PROMPT_TEXT data type id. it is simply treated like any other TEXT type for this application. added a hiddden progress bar below the main text body that will only kick in when it detects a string of the PROG/PROG_LAST data types. refactored "halt" to "yield" on the client's internal command. also refactored "text_settings" to "theme" on the json config file. the config file name will now also include the major version number as a way to verify compatibility as the client is updated. changed the client's versioning system to a 2 number system. more info about this new system was edited into the README.md file. synced the type_id and async_id values with MRCI host. added support for the new MRCI host 4 number versioning system. this client will only care about the tcp_rev part of this new system for now. any changes to the hosts' core commands shouldn't affect compatibility with this client.
2020-03-10 19:04:48 -04:00
* **major**, **minor**, **tcp_rev**, **mod_rev** these 4 numeric values are the host version number that uses a 4 number versioning system. This can be used by the client to setup backwards compatibility or determine of if supports the host at all. If not supported, the client can simply disconnect form the host and display an error to the user.
Initial commit for the Cmdr project.
2019-09-14 13:03:34 -04:00
Major upgrade and changes the MRCI protocol has been upgraded to support branch ids so running multiple instances of the same command can run at the same time at the host side. this client however will still continue to run host commands in FIFO but this is something that can be added in the near future. another change to the protocol is the version negotiation is now entirely one-sided so just the client can now decide of the host version is acceptable or not. the NEW_CMD frames from MRCI host will now include all of the command documentation so listing of all available commands and documentation is now entirely client controlled because the host no longer have built in documentation commands. this client's Session object now operate in it's own thread. for now, this does nothing but this is a prelude for future performance updates that will including multi-threading.
2019-11-23 14:37:41 -05:00
* **sesId** is the session id. It is a unique 224bit sha3 hash that can be used by the host and client to uniquely identify the current session or past sessions.
Initial commit for the Cmdr project.
2019-09-14 13:03:34 -04:00
Major upgrade and changes the MRCI protocol has been upgraded to support branch ids so running multiple instances of the same command can run at the same time at the host side. this client however will still continue to run host commands in FIFO but this is something that can be added in the near future. another change to the protocol is the version negotiation is now entirely one-sided so just the client can now decide of the host version is acceptable or not. the NEW_CMD frames from MRCI host will now include all of the command documentation so listing of all available commands and documentation is now entirely client controlled because the host no longer have built in documentation commands. this client's Session object now operate in it's own thread. for now, this does nothing but this is a prelude for future performance updates that will including multi-threading.
2019-11-23 14:37:41 -05:00
### Async Commands ###
Initial commit for the Cmdr project.
2019-09-14 13:03:34 -04:00
Major upgrade and changes the MRCI protocol has been upgraded to support branch ids so running multiple instances of the same command can run at the same time at the host side. this client however will still continue to run host commands in FIFO but this is something that can be added in the near future. another change to the protocol is the version negotiation is now entirely one-sided so just the client can now decide of the host version is acceptable or not. the NEW_CMD frames from MRCI host will now include all of the command documentation so listing of all available commands and documentation is now entirely client controlled because the host no longer have built in documentation commands. this client's Session object now operate in it's own thread. for now, this does nothing but this is a prelude for future performance updates that will including multi-threading.
2019-11-23 14:37:41 -05:00
Async commands are 'virtual commands' that this application can encounter at any time while connected to the host. More information about this can be found in the [Async.md](Async.md) document. This application does act on some of the data carried by the async commands but not all of them.
Initial commit for the Cmdr project.
2019-09-14 13:03:34 -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.
Versioning system change and support of new MRCI host features added support for the new PROMPT_TEXT data type id. it is simply treated like any other TEXT type for this application. added a hiddden progress bar below the main text body that will only kick in when it detects a string of the PROG/PROG_LAST data types. refactored "halt" to "yield" on the client's internal command. also refactored "text_settings" to "theme" on the json config file. the config file name will now also include the major version number as a way to verify compatibility as the client is updated. changed the client's versioning system to a 2 number system. more info about this new system was edited into the README.md file. synced the type_id and async_id values with MRCI host. added support for the new MRCI host 4 number versioning system. this client will only care about the tcp_rev part of this new system for now. any changes to the hosts' core commands shouldn't affect compatibility with this client.
2020-03-10 19:04:48 -04:00
2. Path of the output makeself file (usually has a .run extension). If not given, the outfile will be named cmdr-x.x.run in the source code folder.
Initial commit for the Cmdr project.
2019-09-14 13:03:34 -04:00
Build:
```
cd /path/to/source/code
sh ./linux_build.sh
```
Install:
```
Versioning system change and support of new MRCI host features added support for the new PROMPT_TEXT data type id. it is simply treated like any other TEXT type for this application. added a hiddden progress bar below the main text body that will only kick in when it detects a string of the PROG/PROG_LAST data types. refactored "halt" to "yield" on the client's internal command. also refactored "text_settings" to "theme" on the json config file. the config file name will now also include the major version number as a way to verify compatibility as the client is updated. changed the client's versioning system to a 2 number system. more info about this new system was edited into the README.md file. synced the type_id and async_id values with MRCI host. added support for the new MRCI host 4 number versioning system. this client will only care about the tcp_rev part of this new system for now. any changes to the hosts' core commands shouldn't affect compatibility with this client.
2020-03-10 19:04:48 -04:00
chmod +x ./cmdr-x.x.run
./cmdr-x.x.run
Initial commit for the Cmdr project.
2019-09-14 13:03:34 -04:00
```
Reference in New Issue Copy Permalink