<labelid="sidebar-toggle"class="icon-button"for="sidebar-toggle-anchor"title="Toggle Table of Contents"aria-label="Toggle Table of Contents"aria-controls="sidebar">
<ahref="print.html"title="Print this book"aria-label="Print this book">
<iid="print-button"class="fa fa-print"></i>
</a>
</div>
</div>
<divid="search-wrapper"class="hidden">
<formid="searchbar-outer"class="searchbar-outer">
<inputtype="search"id="searchbar"name="searchbar"placeholder="Search this book ..."aria-controls="searchresults-outer"aria-describedby="searchresults-header">
<p>ctrl is a Command & Control (C2) backend system for Servers, IOT and Edge platforms. Simply put, control anything.</p>
<p>Example use cases:</p>
<ul>
<li>Send shell commands or scripts to control one or many end nodes that will instruct to change config, restart services and control those systems.</li>
<li>Gather data from both secure and not secure devices and systems, and transfer them encrypted in a secure way over the internet to your central system for handling those data.</li>
<li>Collect metrics or monitor end nodes, then send and store the result to some ctrl instance, or pass those data's on to another ctrl instance for further handling of metrics or monitoring data.</li>
<li>Distribute certificates.</li>
<li>Run as a sidecar in Kubernetes for direct access to the pod.</li>
</ul>
<p>As long as you can do something as an operator in a shell on a system you can do the same with ctrl in a secure and encrypted way to one or all end nodes (servers) in one go with one single message/command.</p>
<p>Ctrl is a system control tool that uses NATS as its messaging architecture. It allows you to send commands using request methods which are then executed on servers. If a receiving node is down, messages are retried based on the criteria set in their body. The results of these methods are delivered back to the
sender.</p>
<p>Ctrl is designed for concurrent processing and can handle multiple messages independently, even if some processes are slow or fail. It's compatible with various host OSs and systems including cloud containers, Raspberry Pi, and others with an installed operating system. Ctrl supports most major architectures such as x86, amd64, arm64, ppc64, and can run on operating systems like Linux, OSX, Windows.</p>
<p>Create a folder which will be the working directory for the node. This is where we keep the .env file, and can mount local host folders to folders within the container.</p>
<p>Start the ctrl container. To be able to send messages into ctrl we mount the readfolder to a local directory. When we later got a messages to send we just copy it into the read folder and ctrl will pick it up and handle it. Messages can be in either YAML or JSON format.</p>
<pre><codeclass="language-bash">docker run --env-file=".env" --rm -ti -v $(PWD)/readfolder:/app/readfolder ctrl:test1
<p>With the above message we send to ourselves since we only got 1 node running. To start up more nodes repeat the above steps, replace the node name under <code>toNodes</code> with new names for new nodes.
NB: If more nodes share the same name the requests will be loadbalanced between them round robin.</p>
<divstyle="break-before: page; page-break-before: always;"></div><h1id="install-on-a-host"><aclass="header"href="#install-on-a-host">Install on a host</a></h1>
<p>Start up a local nats message broker if you don't already have one.</p>
<pre><codeclass="language-bash">docker run -p 4444:4444 nats -p 4444
</code></pre>
<p>Build the ctrl binary from the source code.</p>
For testing we create a folder for the node to store it's data.
```bash
cd /usr/local/ctrl
mkdir node1
cd node1
</code></pre>
<p>ctrl will create all the folders needed like etc, var and more in the current directory where it was started if they don't already exist. This behaviour can be changed with flags or env variables.</p>
<p>Create a .env file for the startup options. Flags can also be used.</p>
<p>If you open another window, and go to the <code>/usr/local/ctrl/node1</code> you should see that ctrl have created the directory structure for you with ./etc, ./var, ./directoryfolder and so on.</p>
<p>Prepare and send a message. We send messages by copying them into the ./readfolder where ctrl automatically will pick it up, and process it.</p>
<p>The handling of all messages is done by spawning up a process for handling the message in it's own thread. This allows us to keep the state of each <strong>individual message level</strong> both in regards to ACK's, error handling, send retries, and reruns of methods for a message if the first run was not successful.</p>
<p>All messages processed by a publisher will be written to a log file after they are processed, with all the information needed to recreate the same message if needed, or it can be used for auditing.</p>
<p>All handling down to the process and message level are handled concurrently. So if there are problems handling one message sent to a node on a subject it will not affect the messages being sent to other nodes, or other messages sent on other subjects to the same host.</p>
<p>Message types of both <strong>ACK</strong> and <strong>NACK</strong>, so we can decide if we want or don't want an Acknowledge if a message was delivered succesfully.
Example: We probably want an <strong>ACK</strong> when sending some <strong>REQCLICommand</strong> to be executed, but we don't care for an acknowledge <strong>NACK</strong> when we send an <strong>REQHello</strong> event.
If a message are <strong>ACK</strong> or <strong>NACK</strong> type are defined by the value of the <strong>ACKTimeout</strong> for each individual message:</p>
<ul>
<li><strong>ACKTimeout</strong> set to 0 will make the message become a <strong>NACK</strong> message.</li>
<li><strong>ACKTimeout</strong> set to >=1 will make the message become an <strong>ACK</strong> message.</li>
</ul>
<p>If ACK is expected, and not received, then the message will be retried the amount of time defined in the <strong>retries</strong> field of a message. If numer of retries are reached, and still no ACK received, the message will be discared, and a log message will be sent to the log server.</p>
<p>To make things easier, all timeouts used for messages can be set with env variables or flags at startup of ctrl. Locally specified timeout directly in a message will override the startup values, and can be used for more granularity when needed.</p>
<h2id="example-of-message-flow"><aclass="header"href="#example-of-message-flow">Example of message flow:</a></h2>
<p>ToNodes to specify several hosts to send message to in the form of an slice/array. When used, the message will be split up into one message for each node specified, so the sending to each node will be handled individually.</p>
<pre><codeclass="language-yaml">data : data here in byte format
</code></pre>
<p>The actual data in the message. This is the field where we put the returned data in a reply message. The data field are of type []byte.</p>
<p>What request method type to use, like REQCliCommand, REQHttpGet..</p>
<pre><codeclass="language-yaml"> methodArgs :
- "bash"
- "-c"
- |
echo "this is a test"
echo "and some other test"
</code></pre>
<p>Additional arguments that might be needed when executing the method. Can be f.ex. an ip address if it is a tcp sender, or the actual shell command to execute in a cli.</p>
<p>ReplyMethod, is the method to use for the reply message. By default the reply method will be set to log to file, but you can override it setting your own here.</p>
<pre><codeclass="language-yaml"> methodArgs :
- "bash"
- "-c"
- |
echo "this is a test"
</code></pre>
<p>Additional arguments that might be needed when executing the reply method. Can be f.ex. an ip address if it is a tcp sender, or the shell command to execute in a cli session.
<p>From what node the message originated. This field is automatically filled by ctrl when left blanc, so that when a message are sent from a node the user don't have to worry about getting eventual repply messages back.
Setting a</p>
<pre><codeclass="language-yaml">ACKTimeout: 10
</code></pre>
<p>ACKTimeout for waiting for an Ack message in seconds.</p>
<p>If the ACKTimeout value is set to 0 the message will become an No Ack message. With No Ack messages we will not wait for an Ack, nor will the receiver send an Ack, and we will never try to resend a message.</p>
<pre><codeclass="language-yaml">retryWait : 60
</code></pre>
<p>RetryWait specifies the time in seconds to wait between retries. This value is added to the ACKTimeout and to make the total time before retrying to sending a message. A usecase can be when you want a low ACKTimeout, but you want to add more time between the retries to avoid spamming the receiving node.</p>
<pre><codeclass="language-yaml">retries : 3
</code></pre>
<p>How many times we should try to resend the message if no ACK was received.</p>
<pre><codeclass="language-yaml">replyACKTimeout int `json:"replyACKTimeout" yaml:"replyACKTimeout"`
</code></pre>
<p>The ACK timeout used with reply messages. If not specified the value of <code>ACKTimeout</code> will be used.</p>
<pre><codeclass="language-yaml">replyRetries int `json:"replyRetries" yaml:"replyRetries"`
</code></pre>
<p>The number of retries for trying to resend a message for reply messages.</p>
<p>Specify the directory structure to use when saving the result data for a repply message.</p>
<ul>
<li>When the values are comma separated like <code>"syslog","metrics"</code> a syslog folder with a subfolder metrics will be created in the directory specified with startup env variable <code>SUBSCRIBER_DATA_FOLDER</code>.</li>
<li>Absolute paths can also be used if you want to save the result somewhere else on the system, like "/etc/myservice".</li>
<p>The fileName field are used together with the directory field mentioned earlier to create a full path for where to write the resulting data of a repply message.</p>
<pre><codeclass="language-yaml">schedule : [2,5]
</code></pre>
<p>Schedule are used for scheduling the method of messages to be executed several times. The schedule is defined as an array of two values, where the first value defines how often the schedule should trigger a run in seconds, and the second value is for how long the schedule are allowed to run in seconds total. <code>[2,5]</code> will trigger the method to be executed again every 2 seconds, but when a total time of 5 seconds have passed it will stop scheduling.</p>
