mirrors/ctrl
1
0
Fork 0
mirror of https://github.com/postmannen/ctrl.git synced 2025-01-09 21:49:16 +00:00
Code Activity
ctrl/doc/book/print.html

357 lines
16 KiB
HTML
Raw Normal View History

Added book
2024-11-17 20:22:35 +00:00
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>ctrl</title>
<meta name="robots" content="noindex">
<!-- Custom HTML head -->
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff">
<link rel="icon" href="favicon.svg">
<link rel="shortcut icon" href="favicon.png">
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/general.css">
<link rel="stylesheet" href="css/chrome.css">
<link rel="stylesheet" href="css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root to javascript -->
<script>
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
</script>
<!-- Start loading toc.js asap -->
<script src="toc.js"></script>
</head>
<body>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script>
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
var sidebar = null;
var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">ctrl</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script>
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h1 id="introduction"><a class="header" href="#introduction">introduction</a></h1>
<p>ctrl is a Command &amp; 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>
<div style="break-before: page; page-break-before: always;"></div><div style="break-before: page; page-break-before: always;"></div><h1 id="install-with-docker"><a class="header" href="#install-with-docker">Install with docker</a></h1>
<p>Start up a local nats message broker</p>
<pre><code class="language-bash">docker run -p 4444:4444 nats -p 4444
</code></pre>
<p>Create a ctrl docker image.</p>
<pre><code class="language-bash">git clone git@github.com:postmannen/ctrl.git
cd ctrl
docker build -t ctrl:test1 .
</code></pre>
<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>
<pre><code class="language-bash">mkdir -p testrun/readfolder
cd testrun
</code></pre>
<p>create a .env file</p>
<pre><code class="language-bash">cat &lt;&lt; EOF &gt; .env
NODE_NAME="node1"
BROKER_ADDRESS="127.0.0,1:4444"
ENABLE_DEBUG=1
START_PUB_REQ_HELLO=60
IS_CENTRAL_ERROR_LOGGER=0
EOF
</code></pre>
<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><code class="language-bash">docker run --env-file=".env" --rm -ti -v $(PWD)/readfolder:/app/readfolder ctrl:test1
</code></pre>
<p>Prepare and send a message.</p>
<pre><code class="language-yaml">cat &lt;&lt; EOF &gt; msg.yaml
---
- toNodes:
- node1
method: REQCliCommand
methodArgs:
- "bash"
- "-c"
- |
echo "some config line" &gt; /etc/my-service-config.1
echo "some config line" &gt; /etc/my-service-config.2
echo "some config line" &gt; /etc/my-service-config.3
systemctl restart my-service
replyMethod: REQNone
ACKTimeout: 0
EOF
cp msg.yaml readfolder
</code></pre>
<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.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="install-on-a-host"><a class="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><code class="language-bash">docker run -p 4444:4444 nats -p 4444
</code></pre>
<p>Build the ctrl binary from the source code.</p>
<pre><code class="language-bash">git clone git@github.com:postmannen/ctrl.git
cd cmd/ctrl
go run build
</code></pre>
<p>Copy the binary to <code>/usr/local</code>.</p>
<pre><code class="language-bash">mkdir -p /usr/local/ctrl
cp ./ctrl /usr/local/ctrl
</code></pre>
<pre><code class="language-bash">
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>
<pre><code class="language-bash">cat &lt;&lt; EOF &gt; .env
NODE_NAME="node1"
BROKER_ADDRESS="127.0.0,1:4444"
ENABLE_DEBUG=1
START_PUB_REQ_HELLO=60
IS_CENTRAL_ERROR_LOGGER=0
EOF
</code></pre>
<p>Start up ctrl. ctrl will automatically used the local .env file we created.</p>
<pre><code class="language-bash">../usr/local/ctrl/ctrl
</code></pre>
<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>
<pre><code class="language-yaml">cat &lt;&lt; EOF &gt; msg.yaml
---
- toNodes:
- node1
method: REQCliCommand
methodArgs:
- "bash"
- "-c"
- |
echo "some config line" &gt; /etc/my-service-config.1
echo "some config line" &gt; /etc/my-service-config.2
echo "some config line" &gt; /etc/my-service-config.3
systemctl restart my-service
replyMethod: REQNone
ACKTimeout: 0
EOF
cp msg.yaml readfolder
</code></pre>
<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.</p>
<h2 id="run-as-service"><a class="header" href="#run-as-service">Run as service</a></h2>
<p>Create a systemctl unit file to run ctrl as a service on the host</p>
<pre><code class="language-bash">progName="ctrl"
systemctlFile=/etc/systemd/system/$progName.service
cat &gt;$systemctlFile &lt;&lt;EOF
[Unit]
Description=http-&gt;${progName} service
Documentation=https://github.com/postmannen/ctrl
After=network-online.target nss-lookup.target
Requires=network-online.target nss-lookup.target
[Service]
ExecStart=env CONFIG_FOLDER=/usr/local/${progName}/etc /usr/local/${progName}/${progName}
[Install]
WantedBy=multi-user.target
EOF
systemctl enable $progName.service &amp;&amp;
systemctl start $progName.service
</code></pre>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
</nav>
</div>
<!-- Livereload script (if served using the cli tool) -->
<script>
const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
const wsAddress = wsProtocol + "//" + location.host + "/" + "__livereload";
const socket = new WebSocket(wsAddress);
socket.onmessage = function (event) {
if (event.data === "reload") {
socket.close();
location.reload();
}
};
window.onbeforeunload = function() {
socket.close();
}
</script>
<script>
window.playground_copyable = true;
</script>
<script src="elasticlunr.min.js"></script>
<script src="mark.min.js"></script>
<script src="searcher.js"></script>
<script src="clipboard.min.js"></script>
<script src="highlight.js"></script>
<script src="book.js"></script>
<!-- Custom JS scripts -->
<script>
window.addEventListener('load', function() {
window.setTimeout(window.print, 100);
});
</script>
</div>
</body>
</html>
Copy permalink