introduction

ctrl is a Command & Control (C2) backend system for Servers, IOT and Edge platforms. Simply put, control anything.

Example use cases:

• Send shell commands or scripts to control one or many end nodes that will instruct to change config, restart services and control those systems.
• 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.
• 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.
• Distribute certificates.
• Run as a sidecar in Kubernetes for direct access to the pod.

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.

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.

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.

Install with docker

Start up a local nats message broker

docker run -p 4444:4444 nats -p 4444

Create a ctrl docker image.

git clone git@github.com:postmannen/ctrl.git
cd ctrl
docker build -t ctrl:test1 .

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.

mkdir -p testrun/readfolder
cd testrun

create a .env file

cat << EOF > .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

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.

docker run --env-file=".env" --rm -ti -v $(PWD)/readfolder:/app/readfolder ctrl:test1

Prepare and send a message.

cat << EOF > msg.yaml
---
- toNodes:
    - node1
  method: REQCliCommand
  methodArgs:
    - "bash"
    - "-c"
    - |
      echo "some config line" > /etc/my-service-config.1
      echo "some config line" > /etc/my-service-config.2
      echo "some config line" > /etc/my-service-config.3
      systemctl restart my-service

  replyMethod: REQNone
  ACKTimeout: 0
EOF

cp msg.yaml readfolder

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.

Install on a host

Start up a local nats message broker if you don't already have one.

docker run -p 4444:4444 nats -p 4444

Build the ctrl binary from the source code.

git clone git@github.com:postmannen/ctrl.git
cd cmd/ctrl
go run build

Copy the binary to /usr/local.

mkdir -p /usr/local/ctrl
cp ./ctrl /usr/local/ctrl

For testing we create a folder for the node to store it's data.

```bash
cd /usr/local/ctrl
mkdir node1
cd node1

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.

Create a .env file for the startup options. Flags can also be used.

cat << EOF > .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

Start up ctrl. ctrl will automatically used the local .env file we created.

../usr/local/ctrl/ctrl

If you open another window, and go to the /usr/local/ctrl/node1 you should see that ctrl have created the directory structure for you with ./etc, ./var, ./directoryfolder and so on.

Prepare and send a message. We send messages by copying them into the ./readfolder where ctrl automatically will pick it up, and process it.

cat << EOF > msg.yaml
---
- toNodes:
    - node1
  method: REQCliCommand
  methodArgs:
    - "bash"
    - "-c"
    - |
      echo "some config line" > /etc/my-service-config.1
      echo "some config line" > /etc/my-service-config.2
      echo "some config line" > /etc/my-service-config.3
      systemctl restart my-service

  replyMethod: REQNone
  ACKTimeout: 0
EOF

cp msg.yaml readfolder

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.

Run as service

Create a systemctl unit file to run ctrl as a service on the host

progName="ctrl"
systemctlFile=/etc/systemd/system/$progName.service

cat >$systemctlFile <<EOF
[Unit]
Description=http->${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 &&
systemctl start $progName.service