Package: pongo-cm
PongoPongo reads scripts from a file, uploads them to remote hosts and executes them there.Write a script once and run it on multiple hostsTarget hosts by tag (eg “webservers” or “aws”)Per-host and per-tag customization via Jinja2 templated configuration filesExample: installing a web application with PongoThis example demonstrates using Pongo to install WordPress on FreeBSD.Create a new directory calledwordpress. This is called the pongo script directory, and must contain a file namedPongofile.
Create a new text file calledwordpress/Pongofile:default:
    script:
        pkg install -y wordpress
        pkg install -y mariadb106-server
        pkg install -y nginx
        pkg install -y wordpress

        rinstall nginx.conf /usr/local/etc/nginx/nginx.conf

        sysrc mysql_enable=YES
        sysrc php_fpm_enable=YES
        sysrc nginx_enable=YES

        service mysql-server start
        service php-fpm start
        service nginx startThis defines a single target nameddefault. The script block is a regular
shell script that will be uploaded to the server and run from within a staging
directory.Other files can be added inside thewordpressscript directory.
All other files will be uploaded to the staging directory,
so as to be available to scripts.
To make this example work you need to place annginx.confinside
the script directory:user www;
worker_processes auto;
error_log /var/log/nginx/error.log;
events {
    worker_connections 1024;
}
http {
    include mime.types;
    default_type application/octet-stream;
    keepalive_timeout 65;
    server {
        listen 80 default_server;
        root /usr/local/www/wordpress;
        index index.php;
        location / {
            try_files $uri $uri/ /index.php?q=$uri&$args;
        }
        error_page 500 502 503 504 /50x.html;
        location = /50x.html {
            root /usr/local/www/nginx-dist;
        }
        location ~ \.php$ {
            try_files $uri =404;
            fastcgi_split_path_info ^(.+\.php)(/.+)$;
            fastcgi_pass localhost:9000;
            fastcgi_index index.php;
            fastcgi_param SCRIPT_FILENAME $request_filename;
            include fastcgi_params;
        }
    }
}Therinstallcommand is a utility script that is always provided in thebin/subdirectory of the staging directory.
It installs the named file to the specified location.Invoke pongo by passing it the path of thewordpressdirectory and a host to run against:pongo --host webserver.example.com wordpressWhat does Pongo do when you run this command?For each host specified,
Pongo opens an ssh connection and creates a temporary staging directory.It populates this staging directory with:therinstall and rsubutility scriptsallscriptblocks from your Pongofile. These are passed through the
Jinja2 templating engine, making it possible to customize scripts per-host.
Scripts are sorted in execution order and numbered.any other files present in your script directory.The final structure might look like this:/tmp/pongo-staging.zikzsvis/wordpress-4bef9a/00.default
/tmp/pongo-staging.zikzsvis/wordpress-4bef9a/nginx.conf
/tmp/pongo-staging.zikzsvis/wordpress-4bef9a/bin/rinstall
/tmp/pongo-staging.zikzsvis/wordpress-4bef9a/bin/rsubPongo then executes all the scripts in order - in this example, only00.defaultOnce all scripts have been executed, Pongo deletes the staging directory and disconnects from the server.PongofilePongo scripts must be contained in a file namedPongofile. This file lists one or more targets, and uses indentation to
indicate structure.Target names form the outermost level. Each target will usually have ascriptdirective, but may contain other directives,
likeenvto set environment variables while running the script orbeforeto indicate a dependency. Here’s an example of some targets from a
file namedsysadmin-tasks/Pongofile:freebsd-update-fetch:
    script:
        freebsd-update fetch

freebsd-update:
    before: freebsd-update-fetch
    env: PAGER=cat
    script:
        freebsd-update installThese targets could be run with the command line:pongo --host <hostspec> sysadmin-tasks freebsd-updateIf no target name is specified on the command line, Pongo will look for a
target nameddefault.DirectivesenvAn environment variable to be set on the server execution. May be specified multiple times.beforeA script that must be run before this one. May be specified multiple times.
TODO: a script from a different file may be selected with the syntaxotherfile.pongo:scriptnameafterA script that must be run after this one. May be specified multiple times.interpreterThe script interpreter to use. defaults to/bin/sh.userThe user to run as, defaulting toroot.
Adding this directive but leaving it empty will cause the script to be run
without elevated privileges.scriptThe text of the script itself.localIf this directive is present, the script will be run on the local machinepipe-fromInput to this script will be piped from the named script.messageA message to be displayed after this script completesconfirmA confirmation step, that must be answered interactively by the user before
the script is run.All directive values are evaluated usingjinja2. You can pass variables to the Jinja2
templating engine by specifying values in theenvironsection of the host
and tag configuration.rinstall and rsubThese are automatically placed into abinsubdirectory of the staging directory.
These files are from therset project, which has informed and inspired the design of pongo.rinstall man pagersub man pageOther filesFiles in the script directory will be uploaded to the staging directory.
Any files with the extension.j2are treated as jinja2 templates
and will be pre-rendered with values loaded from the host’s environ configuration before uploading.Environment variables:PONGO_SSH- the ssh executablePONGO_SSH_OPTS- arguments to pass to sshPONGO_HOST- the current host, as supplied to pongoPONGO_HOSTNAME- the resolved hostname of the current hostPONGO_HOST_IP- the current host’s IP addressPONGO_CONNECT_USER- the username to connect withPONGO_USER- if set, commands will be executed under sudo as the named userOther environment variables can be set in one of the following config files.
These are read in order, with later ones overriding variables set in earlier
ones:pongo.conf.d/environ.jsonpongo.conf.d/tags/<tag>/environ.jsonpongo.conf.d/<hostname>/environ.json(You can also use toml format for these files if you prefer).Environment variables read from these files are subject to template expansion and interpolation, using
Jinja2. For exsmple:# In pongo.conf.d/environ.toml
backup_files='/usr/local /home'

# In pongo.conf.d/<hostname>/environ.toml
backup_files='{{ backup_files }} /var/db'ConfigurationPongo loads its configuration from a directory namedpongo.conf.d. It will search for this:in any location specified by--configin$XDG_CONFIG_HOMEin$HOME/.configThe configuration directory should have the following structure:pongo.conf.d/scriptbase- a file naming the path where script directories will be searched forpongo.conf.d/environ.json- default values supplied to the Jinja templating enginepongo.conf.d/hosts/- a directory containing per-host configuration, explained below.pongo.conf.d/tags/- a directory containing per-tag configuration, explained below.HostsEach host should have a subdirectory containing its configuration. This may contain any of the following files:``pongo.conf.d/hosts/<host>/hostname`` - hostname to use for ssh connection
``pongo.conf.d/hosts/<host>/user`` - user for ssh connection
``pongo.conf.d/hosts/<host>/sudo`` - sudo program to use
``pongo.conf.d/hosts/<host>/tags`` - a list of tags to apply to the host, one per line
``pongo.conf.d/hosts/<host>/environ.json`` - extra environment vairablesTagsHosts can be grouped by tags.
Tag a host by create a file namedpongo.conf.d/hosts/<host>/tags, with one tag per line.
You can add as many tags as you find useful, perhasp tagging by role (egwebserver,database), by technology (egopenbsd,linux), by
location (europe,asia) and so on.Target tagged groups by using the syntax--host@<tag>, eg:pongo --host @freebsd
pongo --host @ovhNote: the special tag@allcan be used to target all hosts.Tags can be configured by adding files underpongo.conf.d/tags/<tag>, for example:``pongo.conf.d/tags/<tag>/environ.json`` - environ variables to apply to all servers with this tag
``pongo.conf.d/tags/<tag>/tags - other tags which are included automaticallyFor example, you might have a tagpostgresql15, which includes the tagpostgresql, which includes the tagdatabase.Ad-hoc scriptsAd-hoc scripts can be run with--command/-c, for example:pongo –host @all –command “uptime”In this case a script directory is not required.OutputPongo outputs all responses from the server to stdout. It also creates a
logging directory named/tmp/pongo-<target>-<date>/. Within this directory
Pongo creates one file per host containing that host’s output.