ccl

README

ccl

A tool to manage a set of podman containers, with a basic configuration defined in a common toml file.

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 are used to set certain default values for containers that reference them. The name of the network must match the name of a predefined podman network. 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.

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

Documentation

Overview

Copyright © 2022 Joel D. Elkins <joel@elkins.co>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.