ccl

A tool to manage a set of podman containers, with a basic configuration defined in a common toml configuration file. In a sense, this tool is a more basic version of docker-compose, except that it defines a whole set of containers in one configuration file, and has much more limited capabilities (e.g., there is no "compose" feature).

Installation

$ go install gitea.elkins.co/Networking/ccl@latest
$ <editor> /etc/ccl.toml

Configuration

There are two arrays of objects that can be defined: Networks and Containers. Currently, no global options are definable.

Networks

Networks refer to pre-existing podman networks. The purpose of configuring them in this file is to set per-container options, e.g., static ips, DNS servers, or whether to enable ipv6. If a static IP is defined for a container, the corresponding network (matching by the "name" property) must have already been configured using podman network create …, and the subnet of the podman network must contain the configured IP address. In my case (and one of the main reasons for this tool), I use macvlan networks, which alters the network configuration somewhat, e.g.: the ipv6 boolean setting for the network is effectively ignored for macvlans. If there is a router sending out RA's, the container will pick up on it and, depending on your podman and host network settings, assign itself an autoconfigured ipv6 address, even when you told podman to disable ipv6. This tool corrects this issue by forcing ipv6 off in the container's network namespace.

You can also set default DNS servers by network, so you don't have to tediously do that for each container.

Containers

A more complex object, but still cut down to a reasonable minimum. Basically most of the information you would need if you typed podman create ... on the command line, is defined in the Container structure. You can define one or more networks, possibly overriding the configured defaults. The network name must be a predefined podman network, but there actaully does not need to be a Network configured for it in this file. Having the podman network defined is enough. Refer to the example below for the fields available to be configured.

One field to point out is Category. Defining a category is optional, but doing so allows you to do operations on multiple containers as a group (e.g. starting, stopping, updating). This concept is distinct to ccl and is not recognized or available to podman itself.

Two Categories are treated specially:

• . (disabled) indicates that containers identified here are to be excluded normally, unless specifically requested by name. This exclusion can be disabled (i.e. disabled containers included in the action) by specifying the -a option.

• all is an implicit category to match all containers (except disabled ones by default, as described above).

Expand for example

[[networks]]
name = "mv2"
dns = ["10.2.0.54", "10.2.0.53"]
ipv6 = true # will allow accepting RAs if the host and podman also do (the default for macvlans)

[[networks]]
name = "mv6"
dns = ["10.6.0.54", "10.6.0.53"]
ipv6 = false # will define a sysctl to disable router advertisements on this interface

[[containers]]
category = "reg"
name = "plex"
hostname = "plex"
image = "docker.io/linuxserver/plex"
cdidevices = [ "nvidia.com/gpu=gpu0" ]
[containers.env]
VERSION = "latest"
TZ = "America/Chicago"
PUID = "996"
PGID = "996"
[[containers.mounts]]
source = "/media"
destination = "/media"
[[containers.mounts]]
source = "/config/plex"
destination = "/config"
[[containers.networks]]
name= "mv2"
ipv4_address = "10.2.1.14"
ipv6_address = "2001:db8:0:2::1:14"
[[containers.networks]]
name= "mv6"
ipv4_address = "10.6.1.14"
ipv6_address = "2001:db8:0:6::1:14"


[[containers]]
category = "reg"
name = "sabnzbd"
hostname = "sabnzbd"
image = "docker.io/linuxserver/sabnzbd"
[containers.env]
PUID = "3010"
PGID = "2130"
TZ = "America/Chicago"
[[containers.mounts]]
source = "/media"
destination = "/media"
[[containers.mounts]]
source = "/config/sabnzbd"
destination = "/config"
[[containers.networks]]
name= "mv2"
ipv4_address = "10.2.1.15"
ipv6_address = "2001:db8:0:2::1:15"
[[containers.networks]]
name= "mv6"
ipv4_address = "10.6.1.15"
ipv6_address = "2001:db8:0:6::1:15"

Shell completion

This tool uses the cobra library, which provides a convenient completion configurator for various shells. Refer to the cobra documentation for info on how to use this feature.

Usage

The following commands are available. All commands accept a list of container names or categories. The tool will take the distinct set of defined containers intersecting the command arguments, and iterate the verb over each of them. If no arguments are provided, it is the same as "all". Invalid (unmatched) container names are silently ignored.

Command/Verb	Description
create	Create the configured containers
ls	List some basic info about the containers
show	Output a toml formatted configuration
start	Start containers. Do nothing for any container already running
restart	Stop then start containers
update	Pull updated images, tear down the configured container, and recreate it
pull	Just pull the configured image. Defined containers unaffected
recreate	Stop, tear down, create, and restart containers (does not pull unless image not found)
rm	Same as podman rm --force
stop	Stop containers
completion	Generate a completion script for fish, zsh, or bash

Refer to ccl help for more info.

Author

Joel D. Elkins joel@elkins.com

License

MIT