diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md index dc10209..a029824 100644 --- a/doc/src/SUMMARY.md +++ b/doc/src/SUMMARY.md @@ -11,6 +11,17 @@ - [Messaging](./core_messaging_overview.md) - [Message fields](./core_messaging_message_fields.md) +- [Request Methods](./core_request_methods.md) - [Nats timeouts](./core_nats_timeouts.md) - [Startup folder](./core_startup_folder.md) - [{{ctrl_DATA}} variable](./core_messaging_ctrl_DATA.md) +- [Errors](./core_errors.md) + +# Example standard messages + +- [Http Get](./example_standard_reqhttpget.md) +- [Tail File](./example_standard_reqtailfile.md) +- [Cli Command](./example_standard_reqclicommand.md) +- [Cli Command Continously](./example_standard_reqclicommandcont.md) +- [Copy Src to Dst](./example_standard_reqcopysrc.md) +- [Send more messages at once](./example_standard_send_more_messages.md) \ No newline at end of file diff --git a/doc/src/core_errors.md b/doc/src/core_errors.md new file mode 100644 index 0000000..793a4cf --- /dev/null +++ b/doc/src/core_errors.md @@ -0,0 +1,11 @@ +# Errors + +Errors happening on **all** nodes will be reported back to the node(s) started with the flag `-isCentralErrorLogger` set to true, or by using the `IS_CENTRAL_ERROR_LOGGER` env variable. + +## Log level + +The log level can also be specified with the `LOG_LEVEL` env variable. Values are `error/info/warning/debug/none`. + +## Debug + +To get more debug information in the logs printed to STDERR the env variable `ENABLE_DEBUG` can be set to true. This will not affect the information printed to the log files, only to STDERR. diff --git a/doc/src/core_request_methods.md b/doc/src/core_request_methods.md new file mode 100644 index 0000000..c6ae270 --- /dev/null +++ b/doc/src/core_request_methods.md @@ -0,0 +1,18 @@ +# Request Methods + +| Method name| Description| +|------------|------------| +|REQOpProcessList | Get a list of the running processes| +|REQOpProcessStart | Start up a process| +|REQOpProcessStop | Stop a process| +|REQCliCommand | Will run the command given, and return the stdout output of the command when the command is done| +|REQCliCommandCont | Will run the command given, and return the stdout output of the command continously while the command runs| +|REQTailFile | Tail log files on some node, and get the result for each new line read sent back in a reply message| +|REQHttpGet | Scrape web url, and get the html sent back in a reply message| +|REQHello | Send Hello messages| +|REQCopySrc| Copy a file from one node to another node| +|REQErrorLog | Method for receiving error logs for Central error logger| +|REQNone | Don't send a reply message| +|REQToConsole | Print to stdout or stderr| +|REQToFileAppend | Append to file, can also write to unix sockets| +|REQToFile | Write to file, can also write to unix sockets| \ No newline at end of file diff --git a/doc/src/example_standard_reqclicommand.md b/doc/src/example_standard_reqclicommand.md new file mode 100644 index 0000000..bebeafd --- /dev/null +++ b/doc/src/example_standard_reqclicommand.md @@ -0,0 +1,98 @@ +# REQCliCommand + +In JSON. + +```json +[ + { + "directory":"system", + "fileName":"system.log", + "toNodes": ["node2"], + "method":"REQCliCommand", + "methodArgs": ["bash","-c","rm -rf ./data & systemctl restart ctrl"], + "replyMethod":"REQToFileAppend", + "ACKTimeout":30, + "retries":1, + "methodTimeout": 30 + } +] +``` + +In YAML. + +```yaml +--- +- toNodes: + - node2 + method: REQCliCommand + methodArgs: + - "bash" + - "-c" + - | + rm -rf ./data & systemctl restart ctrl + + replyMethod: REQToFileAppend + ACKTimeout: 30 + retries: 1 + ACKTimeout: 30 + directory: system + fileName: system.log +``` + +Will send a message to node2 to delete the ctrl data folder, and then restart ctrl. The end result will be appended to the specified file on the node where the request originated. + +## More examples + +### Get the prometheus metrics of the central server + +```json +[ + { + "toNode": "central", + "method": "REQCliCommand", + "methodArgs": [ + "bash", + "-c", + "curl localhost:2111/metrics" + ], + "replyMethod": "REQToConsole", + "methodTimeout": 10 + } +] + +``` + +### Start up a tcp listener for number of seconds + +```json +[ + { + "toNode": "node1", + "method": "REQCliCommandCont", + "methodArgs": [ + "bash", + "-c", + "nc -lk localhost 8888" + ], + "replyMethod": "REQToConsole", + "methodTimeout": 10, + } +] +``` + +The netcat tcp listener will run for 10 seconds before the method timeout kicks in and ends the process. + +### Get the running docker containers from a node + +```json +[ + { + "directory":"some/cli/command", + "fileName":"cli.result", + "toNode": "node2", + "method":"REQnCliCommand", + "methodArgs": ["bash","-c","docker ps -a"], + "replyMethod":"REQToFileAppend", + } +] +``` diff --git a/doc/src/example_standard_reqclicommandcont.md b/doc/src/example_standard_reqclicommandcont.md new file mode 100644 index 0000000..5bb0d69 --- /dev/null +++ b/doc/src/example_standard_reqclicommandcont.md @@ -0,0 +1,19 @@ +# REQCliCommandCont + +The **REQCliCommand** and the **REQCliCommandCont** are the same, except for one thing. **REQCliCommand** will wait until wether the method is finished or the methodTimeout kicks in to send the result as one single message. **REQCliCommand** will when a line is given to either stdout or stderr create messages with that single line in the data field, and send it back to the node where the message originated. + +```json +[ + { + "directory":"some/cli/command", + "fileName":"cli.result", + "toNode": "node2", + "method":"REQCliCommandCont", + "methodArgs": ["bash","-c","tcpdump -nni any port 8080"], + "replyMethod":"REQToFileAppend", + "methodTimeout":10, + } +] +``` + +Example Will run the command given for 10 seconds (methodTimeout), and return the stdout output of the command continously while the command runs. Uses the methodTimeout to define for how long the command will run. diff --git a/doc/src/example_standard_reqcopysrc.md b/doc/src/example_standard_reqcopysrc.md new file mode 100644 index 0000000..504206e --- /dev/null +++ b/doc/src/example_standard_reqcopysrc.md @@ -0,0 +1,28 @@ +# REQCopySrc + +Copy a file from one node to another node. + +```json +[ + { + "directory": "copy", + "fileName": "copy.log", + "toNodes": ["central"], + "method":"REQCopySrc", + "methodArgs": ["./testbinary","ship1","./testbinary-copied","500000","20","0770"], + "methodTimeout": 10, + "replyMethod":"REQToConsole" + } +] +``` + +- toNode/toNodes, specifies what node to send the request to, and which also contains the src file to copy. +- methodArgs, are split into several fields, where each field specifies: + 1. SrcFullPath, specifies the full path including the name of the file to copy. + 2. DstNode, the destination node to copy the file to. + 3. DstFullPath, the full path including the name of the destination file. The filename can be different than the original name. + 4. SplitChunkSize, the size of the chunks to split the file into for transfer. + 5. MaxTotalCopyTime, specifies the maximum allowed time the complete copy should take. Make sure you set this long enough to allow the transfer to complete. + 6. FolderPermission, the permissions to set on the destination folder if it does not exist and needs to be created. Will default to 0755 if no value is set. + +To copy from a remote node to the local node, you specify the remote nodeName in the toNode field, and the message will be forwarded to the remote node. The copying request will then be picked up by the remote node's **REQCopySrc** handler, and the copy session will then be handled from the remote node. diff --git a/doc/src/example_standard_reqhttpget.md b/doc/src/example_standard_reqhttpget.md new file mode 100644 index 0000000..7e11fd6 --- /dev/null +++ b/doc/src/example_standard_reqhttpget.md @@ -0,0 +1,41 @@ +# REQHttpGet + +In JSON. + +```json +[ + { + "directory": "httpget", + "fileName": "finn.no.html", + "toNodes": ["node1","node2"], + "method":"REQHttpGet", + "methodArgs": ["https://finn.no"], + "replyMethod":"REQToFile", + "ACKTimeout":5, + "retries":3, + "methodTimeout": 5 + } +] +``` + +In YAML. + +```yaml +--- +- toNodes: + - ["node1","node2"] + method: REQHttpGet + methodArgs: + - "https://finn.no" + replyMethod: REQToFile + ACKTimeout: 5 + retries: 3 + methodTimeout: 5 + directory: httpget + fileName: finn.no.html +``` + +The result html file of the http get will be written to: + +- \\httpget\node1\finn.no.html +- \\httpget\node2\finn.no.html diff --git a/doc/src/example_standard_reqtailfile.md b/doc/src/example_standard_reqtailfile.md new file mode 100644 index 0000000..93623bb --- /dev/null +++ b/doc/src/example_standard_reqtailfile.md @@ -0,0 +1,39 @@ +# REQTailFile + +In JSON. + +```json +[ + { + "directory": "tails", + "fileName": "some.log", + "toNodes": "node1","node2","node3", + "method":"REQTailFile", + "methodArgs": ["/var/log/syslog"], + "ACKTimeout":5, + "retries":3, + "methodTimeout": 200 + } +] +``` + +NB: If no replyMethod are specified, it will default to **REQToFile** + +In YAML. + +```yaml +--- +- toNodes: + - ["node1","node2","node3"] + method: REQTailFile + methodArgs: + - "/var/log/syslog" + replyMethod: REQToFile + ACKTimeout: 5 + retries: 3 + methodTimeout: 5 + directory: tails + fileName: var_log_syslog.log +``` + +The above example will tail the syslog file on 3 nodes for 5 seconds, and save the result on the node where the request came from in the local `data` folder. diff --git a/doc/src/example_standard_send_more_messages.md b/doc/src/example_standard_send_more_messages.md new file mode 100644 index 0000000..ffb85c4 --- /dev/null +++ b/doc/src/example_standard_send_more_messages.md @@ -0,0 +1,26 @@ +# Send more messages + +```json +[ + { + "directory":"cli-command-executed-result", + "fileName": "some.log", + "toNode": "ship1", + "method":"REQCliCommand", + "methodArgs": ["bash","-c","sleep 3 & tree ./"], + "ACKTimeout":10, + "retries":3, + "methodTimeout": 4 + }, + { + "directory":"cli-command-executed-result", + "fileName": "some.log", + "toNode": "ship2", + "method":"REQCliCommand", + "methodArgs": ["bash","-c","sleep 3 & tree ./"], + "ACKTimeout":10, + "retries":3, + "methodTimeout": 4 + } +] +```