push.php.json

The push.php-file is the interface to the user. It allows to:

generate configurations for hosts
push new configurations to hosts
compare the current configuration of a host against a generated one
execute commands on a host

and a few other things.

Usage

push.php

Usage:
  command [options] [arguments]

Options:
  -h, --help  Display this help message

Available commands:
  help                       Displays help for a command
  list                       Lists commands
 configuration
  configuration:allgenerate  Generate configuration for all associated templates/confs (and copy non-template files) for host(s) from inventory
  configuration:diffsync     Diff or sync configuration from local directories to remote host(s) from inventory
  configuration:generate     Generate configuration from templates (and copy non-template files) for host(s) from inventory
 dynamic
  dynamic:acquire            Acquire dynamic data from host(s) from inventory
  dynamic:show               List and show dynamic data for host(s) from the inventory
 inventory
  inventory:add              Add a host to the inventory
  inventory:check            Check IP attribute for host(s) from the inventory
  inventory:list             List and show attributes for host(s) from the inventory
  inventory:remove           Remove a host from the inventory
  inventory:set              Set attribute for a host in the inventory
 push
  push:active                Shows hosts that react to a 'ping'
  push:command               Executes for the given hosts the given template command
  push:openssh               Shows hosts with open ssh port
  push:poweroff              Powers down hosts with no logged in users or lists the logged in users
  push:reboot                Reboots hosts with no logged in users or lists the logged in users
  push:wakeonlan             Wake on Lan

Note that all commands are prefix-unique and that this allows to call a command in a faster way. For example instead of using:

configuration:allgenerate you could simply use c:a
push:difffiles you could simply use p:d

Workflow

The general work flow when using push to handle host configuration files is to:

Create/Update the network.json-file by hand if need be. This is the case whenever a new network host group is added. (see: network.json)
Create/Update the inventory.json-file using the inventory:xxx-commands of push. (see: inventory.json)
In case no dynamic data for the host exists, collect the dynamic data (/etc/network/interfaces and /etc/fstab) using dynamic:acquire.
Generate the files which need to be synched to the host using the configuration:xxx-commands of push.
Compare the generated configuration files of a host against the existing configuration using the configuration:diffsync-command of push.
Copy/Apply the newly generated configuration files to the host using the configuration:diffsync-command of push.

Commands

Here's what each of the command is used for.

help

The help command displays help for a given command.

Usage

push.php help [options] [--] [<command_name>]

command_name: The command name [default: "help"].
Options
- --format=FORMAT The output format (txt, xml, json, or md) [default: "txt"]
- --raw To output the raw command help.
- -h|--help Display this help message

Calling

`push.php help list' shows the help for the list-command
push.php help --format=xml list shows the help for the list command as xml.
`push.php help configuration:allgenerate' shows the help for the configuration:allgenerate-command

list-command

List the known commands optionally in a specific format and only for a given namespace.

Usage

push.php list [--raw] [--format FORMAT] [--] [<namespace>]

--raw: use raw text output without color formation and indention
--format FORMAT: output the list in a given format. Supported FORMAT values are txt, xml, json and md.
--: indicate that the next parameter is the namespace
namespace: only list the command for a specifc namespace. configuration, dynamic, inventory and push are the names of the currently known namespaces.

configuration:allgenerate-command

The configuration:allgenerate-command is used to generate the configuration files for a given host, or each host from a given group, and all the templates the host is associated to.

Usage

push.php configuration:allgenerate [-c|--clear] [--] <templates folder> <target> <group>

-c|--clear: clear any existing folder for the host inside the target directory before processing the associated templates.
--: indicate that the next parameter is the template folder.
templates folder: absolute path to the 'var'-folder in which a the templates are located.
target: directory in which a folder with the hostname will be created and the generated configuration files for that host will be placed in.
group: the name of a host or group of hosts for which the configuraiton files should be generated. The special group 'all' isn't allowed here.

Calling

push.php configuration:allgenerate /root/push/var/ /root/push/tmp server02 -c will check whether a 'server02'-subfolder inside the '/root/push/tmp'-folder exists and delete it in case it does. After this a new 'server02'-subfolder will be created and all generated configuration files will be placed into it.
push.php configuration:allgenerate /root/push/var/ /root/push/tmp server02 will create a new 'server02'-subfolder inside the '/root/push/tmp'-folder in case it doesn't exist. In case the folder exists only generated files will be overwritten. Files which are not covered by an associated template will remain untouched.
push.php configuration:allgenerate /root/push/var/ /root/push/tmp workstations -c will clear and recreate the configuration files for all hosts inside the workstations-group and their associated templates.

To be on the save side of things, it is adviced to always use the -c-parameter together with the configuration:generateall command to make sure no lingering old files are accidentally pushed to a host.

configuration:diffsync-command

The configuration:diffsync-command is used to compare either compare the content of a folder agains a remote folder or push/synchronize a given folder to a target host (or hosts inside a group).

Usage

push.php configuration:diffsync [-s|--sync] [--] <source> <target> <group>

-s|--sync: indicates that the content should be synchonized/copied to the host instead of just be compared.
--: indicate that the next parameter is the source
source: absolute path to the folder in which the generated configuration for host X resides in a subdirectory named X. (source: '/var/push/tmp', location of configuration files for host X: '/var/push/tmp/X')
target: target base path on the target host to which the content of the configuration files should be copied/compared to.
group: the name of a host or group of hosts. 'all' is a special group which contains all hosts.

Calling

push.php configuration:diffsync /root/push/var/ / servers compares the content of the '/root/push/var/' on the server with the content inside the '/'-folder of the host system for each host associated to the servers-group.
push.php configuration:diffsync /root/push/var/ /var/tmp server02 -s synchronizes/copies the content of the local '/root/push/var/server02'- to the '/var/tmp'-folder on host (server02). Important: One should always first compare a generated configuration against the target host before synchronizing/copying it to the target. Only add -s|--sync after you made sure the changes are okay.

configuration:generate-command

The configuration:generate-command is used to generate the configuration files of a single template for a host or a group of hosts. Calling this command with different templates allows to combine multiple templates. Note that this also allows to generate configuration files for templates which are normally not associated to a host. When adding a new client to the inventory this also allows to just update the DHCP and/or DNS configuration of a server without having to care about any other configuration. (see: 'Server/Rechner hinzufügen')

Usage

push.php configuration:generate [-c|--clear] [--] <source> <target> <group>

-c|--clear: clear any existing folder for the host inside the target directory before processing the templates
--: indicate that the next parameter is the source (template folder).
source: absolute path to the folder which contains the template which should be processed.
target: directory in which the template should be evaluated to. Normally this should be the absolute path of the tmp-folder. Inside the target folder a subfolder with the hosts name will be created.
group: the name of a host or group of hosts. The special group 'all' isn't allowed here.

Calling

push.php configuration:generate /root/push/var/kerberos_client /root/push/tmp pc07 -c would delete the '/root/push/tmp/pc07'-folder in case it existed. Create a new '/root/push/tmp/pc07'-folder and put the files form the evaluation og the kerberos_client-template inside it.
this command multiple times for different templates:
```
push.php configuration:generate /root/push/var/client /root/push/tmp pc42 -c
push.php configuration:generate /root/push/var/kerberos_client /root/push/tmp pc42
push.php configuration:generate /root/push/var/server_lxd /root/push/tmp pc42
```
would create a configuration for pc42 based on the client-, kerberos_client- and server_lxd-template. Most of the time this command is probably not needed since normally configuration:allgenerate is the better way to go.

dynamic:acquire-command

The `dynamic:acquire-command is ment to aquire some host specific data from the target host which will be saved inside the tmp/dynamic.json-file and thus be available during processing of the templates.

Usage

push.php dynamic:acquire <group> <attributes> (<attributes>)...

group: the name of a host or group. 'all' is a special group which contains all hosts.
attributes: one or multiple attributes to collect. Supported attribures to collect are:
- fstab collects the current entries of the '/etc/fstab'-file. Note atm. all active entries from the fstab will be copied. Due to this, manual adjustment might be necessary in case some of those entries should not be kept.
- interface find the name of the current output interface by calling 'ip -o link show' on the target host and collecting the interface which has the MAC-address associates with the host (inside the inventory.json).

Calling

push.php dynamic:acquire pc07 interface fstab updates the tmp/dynamic.json-file with the newly collected data for pc07.
push.php dynamic:acquire workstations interface updates the tmp/dynamic.json-file with the newly collected data for all hosts associated with the workstations-group. This call will on update the interface-data, any existing fstab-data will be untouched through this.

Note: When collecting fstab-data all entries from the fstab of the host will be collected. Thus one needs to check that only the wanted entries are stored inside the tmp/dynamic.json-file. Typically only entries which map to physical devices are wanted. Mounting of network shares or similar should be covered through templates and not be part of the dynamic.json-file.

dynamic:show-command

Shows all or parts of the collected dynamic data for a host or a group of hosts.

Usage

push.php dynamic:show <group> [<attributes>]...

group: the name of a host or group of hosts. 'all' is a special group which contains all hosts.
attributes: restrict the output to only show specific attributes.

Calling

push.php dynamic:show servers shows all the dynamic data collected for any host associated to the servers-group.
push.php d:s server02 fstab shows just the fstab-data for server02.

inventory:add-command

Adds a new host entry to the inventory, but can also be used to associate the host with a group.

Usage

push.php inventory:add [-m|--mac MAC] [-g|--group GROUP] [--] <name>

-m|--mac MAC set the MAC address for the host.
-g|--group GROUP set a group for the host. 'all' is a special group which contains all hosts. No host needs to be added to it manually.
--: indicate that the next parameter is the name of the host.
name: the name of the host. The name needs to consist of '', where the hostgroup needs to be the a hostgroup from the network.json and number needs to be between 1 to 199.

Calling

push.php inventory:add -m de:le:te:me pc99 would create a new entry inside the inventory. Assuming there is a hostgroup named 'pc' with a range of '192.168.0.23' the entry will look like this:
```
"pc99": {
  "mac": "de:le:te:me",
  "ip4": "192.168.0.99"
},
```
Note that the 'ip4' automatically gets assigned using the range of the hostgroup and the number from the name.
push.php inventory:add -g workstations pc99 would associate the host (pc99) to the workstations group. This would expand the above pc99-entry to:
```
"pc99": {
  "mac": "de:le:te:me",
  "ip4": "192.168.0.99",
  "groups: {
    "workstations*
  }
},
```

inventory:check-command

Checks whether a host or all hosts of a group have an IP and whether its 'ip4'-value inside the inventory.json matches the ip it should have based on it's name (and hostgroup association).

Usage

inventory:check [-r|--repair] [--] <group>

-r|--repair adjusts the ip of the host(s) to the one it/they should have based on their name and hostgroup association.
--: indicate that the next parameter is the group-parameter.
group: the name of a host or group of hosts to process. 'all' is a special group which contains all hosts.

Calling

push.php i:c all checks for each of the hosts whether it got the expected ip4 value.
push.php inventory:check --repair pc99 repairs the ip4 value of the host named pc99 based on it's name and hostgroup association.

inventory:list-command

List attributes inside the inventory for a host or all hosts associated to a group.

Usage

push.php inventory:list [-a|--attribute ATTRIBUTE] [-A|--all] [--] <group>

-a|--attribute ATTRIBUTE: additionally to the hostname list the given attribute value for the host(s).
-A|--all: additionally to the hostname list all attributes of the host(s).
--: indicate that the next parameter is the group
group: the name of a host or group. 'all' is a special group which contains all hosts.

Calling

push.php i:l workstations, a list of all the names of all hosts associated to the workstations-group will be shown.
push.php i:l server_ldap, a list of the names of all hosts associated to the server_ldap-group will be shown.
push.php i:l -a ip4 server_nfs, a list of all NFS servers and their ip4-attribute will be shown.
push.php i:l -a ip4 server04, the hostname and ip4 of server04 will be shown..
push.php i:l -a groups all, a list of all hosts and their associated groups will be shown.
push.php i:l -a ip4 -a groups pc07, the ip4- and the groups-value of host pc07 will be shown.

A typical usage example for this is when a new host should be added but one doesn't know the name that was used for a the last host in the targeta hostgroup. So when adding a new PC we would first call push.php i:l workstations to see which names are already taken. With pc20 being the last workstation inside the inventory we would name the new workstation pc21.

inventory:remove-command

Removes a given host from the inventory. Note that there is no saveguard so only use this if you really want to remove a host from the inventory. This will not change the content of the dynamic.json-file.

Usage

push.php inventory:remove <name>

name: the name of the host that should be removed. Groups can't be used here.

Calling

push.php inventory:remove pc17 will removes the data entry for pc17 from the inventory.json-file.

inventory:set-command

Set a an attribut for a host.

Usage

push.php inventory:set [-a|--array] [-c|--clear] [-r|--remove] [--] <name> <attribute> [<values>]...

-a|--array: indicates that the attribute is an array and values are added to it.
-c|--clear: clear an array (before adding potential values, --array is implied).
-r|--remove: Remove the attribute from the host. If the attribute is an array this will delete the whole array.
--: indicate that the next parameter is the name.
name: the name of the host to modify. Groups are not allowed here.
attribute: The name of the attribute to set.
values: The value(s) to set the attribute to (if multiple given or array already present, --array is implied)

Calling

push.php inventory:set -r -- pc07 ip4 will remove the 'ip4' attribute of host pc07 from the inventory. I case of the 'ip4'-attribute, this could be repaired using push.php inventory:check -r pc07.
push.php i:s -c pc07 confs will remove all entries inside the 'confs' array for host pc07.
push.php i:s -c pc07 confs client will remove all entries inside the 'confs' array for host pc07 and then add 'client' as a new entry.
push.php i:s pc07 description "What a wonderful day!" will add an attribute named description (in case it doesn't exist) to host pc07 and set it's value to 'What a wonderful day!'.
push.php -a i:s pc07 testing 1 2 3 will create an array called testing with the entries: 1:1, 2:1 and 3:1 to the host pc07. If there already is an array called 'testing' the new values will be added if they don't exist. If there is an attribut named 'testing' which isn't an array, the attribut will be converted to an array keeping it's existing value(:1) and adding the new values.
push.php i:s pc07 test 2 3 will create an array names 'test' and add '2:1' and '3:1' as values in case test doesn't exist. If test exists and is an array '2:1' and '3:1' will be added in case they don't exist. If test isn't an array but exists the command will first set the value of 'test' to '2:1' and then to '3:1'.

To keep things simple always use '-a|--array' when dealing with arrays.

push:active-command

Shows hosts that react to a 'ping', which is a decent indicator to determine whether the host is active/online or not.

Usage

push.php push:active <group>

group: the name of a host or group of hosts to check. 'all' is a special group which contains all hosts.

Calling

`push.php push:active pc07 will try to ping host pc07* and report whether it could be reached or not.
`push.php push:active all* will try to ping all hosts and report for each whether it could be reached or not.

push:command-command

Call a specific command on a host or group.

Usage

push.php push:command <group> <template>

group: the name of a host or group. 'all' is a special group which contains all hosts.
template the command to call

Note that this will show the output of the called command, but it does not offer any additional interaction with the host. So you will be stuck when a command requires additional user input.

Calling

push.php push:command workstations "apt-get update" will connect to each host associated to the 'workstations'-group and call apt-get update on it.
push.php push:command pc07 "apt-get -y dist-upgrade" will connect to host pc07 and call apt-get -y dist-upgrade on it.

Note that the template-command by default will be called as the current user (typically root), if you want to call it as another user you need to adjust the template-call to execute your command as another user. In example by using something like sudo -u <remoteuser> sh -c <command> as template-call.

push:openssh-command

Checks whether the open ssh port (22) is open on the host/group. Since most non-pcs to not support ssh and consequentyl don't have an open ssh port you might want to use push:active instead to determine if those hosts are active.

Usage

push.php push:openssh <group>

group: the name of a host or group of hosts. 'all' is a special group which contains all hosts.

Calling

push.php push:openssh workstations will report which host associated to the workstations-group have an open port 22.

push:poweroff-command

Turns off a host or group of hosts with no logged in users or lists the logged in users.

Usage:

push.php push:poweroff <group>

group: the name of a host or group of hosts. 'all' is a special group which contains all hosts.

Calling

push.php push:poweroff workstations connects to each host associated to the workstations group, checks the number of users that are logged in and, if there are no other users logged in, shuts the host down. In case other users are logged in, the user list will be printed.

push:reboot-command

Reboots a host or group of hosts with no logged in users or lists the logged in users.

Usage

push.php push:reboot <group>

group: the name of a host or group. 'all' is a special group which contains all hosts.

Calling

push.php push:poweroff reboots connects to each host associated to the workstations group, checks the number of users that are logged in and, if there are no other users logged in, reboots the host. In case other users are logged in, the user list will be printed.

push:wakeonlan-command

Sends a wake-on-lan magic ethernet package to the host or groups of hosts.

Usage

push.php push:wakeonlan <group>

Calling

push.php push:wakeonlan all send a magic package for wake-on-lan to each of the hosts.

General usage remarks

Here are some general remarks for using the push.php executable.

Always make sure you compare a configuration against the current state before sending it to a server.
Normally old genmerated configurations should be cleared before generateing new ones to avoid unwanted old files to be synchonized.
Make sure to read 'Server/Rechner hinzufügen' when adding new clients or servers.
Before generating a configuration for a new host make sure you collected it's dynamic data and added everything needed for it to the inventory.
Make sure you can passwordless ssh to the target host before acquiring dynamic data, pushing or comparing a configuration. (i.e. use ssh-copy-key <hostIP> on the server)