inventory.json

The inventory.json-file needs to be located inside the etc-folder. It can be created by hand, but it is normally adviced to use:

• push.php inventory:add -m <host MAC> <hostname> to add a new host with a specific MAC address.
  • Note the hostname needs to consist of <hostgroup><number>, where the hostgroup needs to be a hostgroup from the network.json and number needs to be between 1 to 199.
• push.php inventory:add -g <groupname> <hostname> to add the host to a group of hosts. Call this multiple times to add the host to multiple groups. These group associations are not related to the hostgroups from the 'network.json'-file.
• push.php inventory:set -a confs <confname> to associate the host with a configuration/template. Call this multiple times to associate the host to multiple configurations/templates.
  • Note the confname needs to be the name of a folder inside the var-folder.

There are further option manipulating the inventory.json- using push.php inventory, see: push.php.

Required attributes

There are attributes which are required for each host, namely:

• A name which associates them to one of the entries in the hostgroup in the network.json-file.
• mac: the MAC-address of the host. (Set by push.php inventory:add -m <host MAC> <hostname>.)
• ip4: the IPv4-address that of the host. (Automatically assinged based on it's name / hostgroup association.)

Example

"scanner01": {
    "mac": "du:mm:yV:al:ue:01",
    "ip4": "1.1.1.1"
},

Hosts to which we push no configuration to (i.e. to phones, printers and similar) do not need any other attributes.

General optional host attributes

There are attributes which are not required but will expand/influence the configuration file generation.

• cname: array of additional names for the host under which it should listed by the local dns server(s).
• groups: We allow to group hosts by associating them to a specific group. Associtations to groups does not influence the way hosts gets configured. It's just a way to group hosts which we use to call push.php-commands on multiple clients. (see: push.php) A host can belong to multiple groups.

Example

"scanner01": {
    "mac": "du:mm:yV:al:ue:01",
    "ip4": "1.1.1.1",
    "groups": {
        "scanners": true,
      "rented": true,
    },
    "cname": {
        "scan01": true
    }
},

Templates/Confs

The following templates exist. And are presented as folders in the var-folder.

• client: The base template for all normal PCs.
• kerberos_client: Configuration files for all machines that are Kerberos clients.
• server: Base configuration files for all servers.
• server_cups: Template for configuration files for hosts which run a CUPS-server for the domain. Note: We assume that there can only be one CUPS server per network domain.
• server_dhcp: Template for configuration files for hosts which run a ISC-DHCP-server for the domain. Note: We assume that there can be no more than two dhcp servers per network domain.
• server_dns_castle: Template for configuration files for hosts which run a BIND/DNS-server for the castle domain.
• server_dns_loft: Template for configuration files for hosts which run a BIND/DNS-server for the loft domain.
• server_kdc: Template for configuration files for hosts which run a Kerberos Key Distribution Center for the domain.
• server_kdm: Tempalte for configuration files for hosts which run a Kerberos Key Distribution Manager for the domain.
• server_ldap: Template for configuration files for hosts which run an OpenLDAP-server for the domain.
• server_lxd: Template for configuration files for hosts which run an LXD-server. (see: LXD Conainer)
• server_nfs: template for configuration files for hosts which run an NFS Kernel Server for the domain.
• server_samba_castle : Template for configuration files for hosts which run a [SAMBA]()-server for the castle-domain. Note: We assume there is only one SAMBA server per domain.
• server_samba_loft: Template for configuration files for hosts which run a SAMBA-server for the loft-domain. Note: We assume there is only one SAMBA server per domain.
• server_vbox: Template for configuration files for hosts which run a VirtualBox-server for the domain.
• server_web: Template for configuration files for hosts which run a web-server inside the domain.
• router_castle: Template for configuration files for the router of the castle-domain.
• router_loft: Template for configuration files for the router of the loft-domain.
• kioskpi: Some configuration files for our KioskPis (WIP).
• lightpi: Some configuration files for our LightPis (WIP).

To specify that a host is associated to one or more templates, the names of those templates need to be added to the confs-array for that host. It is typical that a single host is associated to multiple templates.

Example

For an NFS server which uses Kerberos we could for example use:

"server199": {
  "mac": "du:mm:yV:al:ue:02",
  "ip4": "2.2.2.2",
  "confs": {
    "server": true,
    "server_nfs": true,
    "kerberos_client": true
  },
  "shares": {
      "\/var\/nfs\/home": {
          "range": "10.66.0.0\/16",
          "share": "\/var\/nfs\/home",
          "target": "\/home"
      },
  }
}

Note that aside from just adding those templates to the confs-array we also added the shares-attribut which is required for the NFS server configuration.

Additional and optional attributes for templates

Some of the above templates require additional attributes and others have optional attributes which are not required, but allow further configuration.

client

The base template for all normal PCs.

• groups: we associate all client hosts to the 'workstations'-group.
• required attributes: aside from the always required 'ip4'- and 'mac'- attribute there are no required attributes for this template.
• optional attributes: no optional attributes exist.
• gimmick attributes: attributes that don't expand the configuration, but hold some meta data:
  • location: describing where this host is located and/or who usually uses it.
  • graka: describing the graphic card that is used in the host.
• influenced by: the evaluation of the client-template is influenced by:
  • the names of all servers that are associated to:
  • server_cups (etc/cups/client.conf.twig)
  • server_ldap (etc/ldap/ldap.conf.twig, etc/ldap.conf.twig)
  • server_nfs and their entries under the shares-attribute (etc/fstab.twig)
  • whether the host itself is associated to:
  • kerberos_client (etc/ldap/ldap.conf.twig, etc/pam.d-folder, etc/ssh/ssh_config.twig, etc/ssh/sshd_config.twig)
  • lxd_client (etc/fstab.twig)
  • the interface that is saved inside the dynamic.json-file for the host. (etc/network/interface.twig)
  • it's own name (etc/hostname.twig, etc/hosts.twig)
  • the cnames that are associated to it (etc/hosts.twig)
  • the current network domain from the network.json-file (etc/hosts.twig, etc/ldap.conf.twig)

kerberos_client

Template for configuration files for all hosts that are Kerberos clients.

• groups: no special group is usually selected for Kerveros clients.
• required attributes: no required attributes.
• optional attributes: no optional attributes which expand the configuration.
• gimmick attributes: no gimmick attributes we usually add for meta data.
• influenced by: the evaluation of the kerberos_client-template is influenced by:
  • all servers that are associated to:
    • server_kdc, their kerberos_name (etc/krb4.conf.twig)
    • server_kdm, their kerberos_name (etc/krb4.conf.twig)
  • the current network domain from the network.json-file (etc/krb4.conf.twig)

server

Base template for all our servers.

• groups: we associate all client hosts to the 'servers'-group.
• required attributes: There are no required attributes.
• optional attributes:
  • hosts_additions: additional entries that will be associated with the hosts IPv4 address (etc/hosts.twig)

    "hosts_additions": {
    "x.example.org redmine.example.org mediawiki.example.org": true,
    "x.example.com redmine.example.com mediawiki.example.com": true
    },

• gimmick attributes: no gimmick attributes we usually add for meta data.
• influenced by: the configuration of the server-template is influenced by:
  • the names of all servers that are associated to:
  • client (/etc/hosts.allowed, etc/idmapd.conf.twig)
  • server (/etc/hosts.allowed, etc/idmapd.conf.twig)
  • server_ldap (etc/ldap/ldap.conf.twig, etc/ldap.conf.twig)
  • server_nfs and their entries under the shares-attribute (etc/fstab.twig)
  • whether the host itself is associated to:
  • kerberos_client (etc/ldap/ldap.conf.twig, etc/pam.d-folder, etc/ssh/ssh_config.twig, etc/ssh/sshd_config.twig, /etc/hosts.allowed.twig)
  • server_nfs (etc/idmapd.conf.twig)
  • lxd_client (etc/fstab.twig, etc/cron.d/crontab-server.twig)
  • the interface that is saved inside the dynamic.json-file for the host. (etc/network/interface.twig)
  • it's own name (etc/hostname.twig, etc/hosts.twig)
  • the cnames that are associated to it (etc/hosts.twig)
  • the current network domain from the network.json-file (etc/hosts.twig, etc/ldap.conf.twig)

server_cups

Template for configuration files for hosts which run a CUPS-server for the domain.

• groups: we associate all CUPS servers to the 'cups'-group.
• required attributes: There are no required attributes.
• optional attributes: There are no optional attributes which would expand the configuration.
• gimmick attributes: we usually add no gimmick attributes for meta data.
• influenced by: the evaluation of the server_cups-template is not influenced by other templates or attributes.

server_dhcp

Template for configuration files for hosts which run a ISC-DHCP-server for the domain.

• groups: we associate all host associated to the 'server_dhcp'-template to the 'dhcp'-group.
• required attributes:
  • dhcp_master: whether the current host is the master DHCP server. This attribute is only required if there are more than one dhcp server in the network. (etc/dhcp/dhcpd.conf.twig)
• optional attributes: There are no optional attributes which would expand the configuration.
• gimmick attributes: There are no gimmick attributes we usually add for meta data.
• influenced by: the evaluation of the server_dhcp-template influenced by
  • the interface that is saved inside the dynamic.json-file for the host. (etc/default/isc-dhcp-server.twig)
  • it's own bridge-attribute in case it's also associated to server_lxd (etc/default/isc-dhcp-server.twig)
  • it's own dhcp_name (etc/dhcp/dhcpd.conf.twig)
  • the current network domain, startaddress, routers, netmask, dhcp ranges rangemin and rangemax from the network.json-file (etc/dhcp/dhcpd.conf.twig)
  • whether the host itself is associated to:
    • server_lxd (etc/default/isc-dhcp-server.twig)
    • server_dhcp, their dhcp_name and their ipv4 (etc/dhcp/dhcpd.conf.twig)
  • all hosts, their name, ip4 (etc/dhcp/hosts.conf.twig)

server_dns_castle / server_dns_loft

Template for configuration for our bind9/dns-servers of the 'castle'/'loft' domain.

• groups: we associate all DNS hosts to the 'dns'-group.
• required attributes: There are no required attributes.
• optional attributes: There are no optional attributes which would expand the configuration.
• gimmick attributes:
  • cnames: each dns server in a domain gets a unique cname 'dnsXX'.
• influenced by: the evaluation of the severdns(castle/loft)-template is influenced by:
  • the zone file of other domains (etc/bind/zone.loft, etc/bind/named.conf.local.twig)
  • the current network domain from the network.json-file (etc/bind/zone.(castle/loft).twig, etc/bind/zone.(castle/loft).reverse.twig, etc/bind/named.conf.local.twig)
  • the nameservers from the network.json-file (etc/bind/zone.(castle/loft).reverse.twig)
  • the subnet from the network.json-file (etc/bind/zone.(castle/loft).reverse.twig, etc/bind/named.conf.local.twig)
  • the name and ip4 associated with each host inside the current domain (etc/bind/zone.(castle/loft).twig, etc/bind/zone.(castle/loft).reverse.twig, etc/bind/named.conf.local.twig)
  • the cnames associated with each host inside the current domain (etc/bind/zone.(castle/loft).twig)

server_kdc

Template for configuration files for hosts which run a Kerberos Key Distribution Center for the domain.

• groups: we associate all cups servers to the 'kdc'-group.
• required attributes:
  • kerberos_name: a cname or hostname under which the server can be found.
• optional attributes: There are no optional attributes which would expand the configuration.
• gimmick attributes:
  • We add a cname like kdcXX for the host to identify it as a kdc server to others.
• influenced by: the evaluation of the server_kdc-template is not influenced by other templates or attributes.

server_kdm

Template for configuration files for hosts which run a Kerberos Key Distribution Manager for the domain.

• groups: we associate all kdm servers to the 'kdm'-group.
• required attributes:
  • kerberos_name: a cname or hostname under which the server can be found
• optional attributes: There are no optional attributes which would expand the configuration.
• gimmick attributes: There are no gimmick attributes we usually add for meta data.
• influenced by: the evaluation of the server_kdm-template influenced by:
  • the number of kdc servers inside the domain (etc/cron.d/crontab.kdm.twig)
  • the current network domain from the network.json-file (etc/cron.d/crontab.kdm.twig)
  • the name of each kdc server inside the domain (etc/cron.d/crontab.kdm.twig)

server_lxd

Template for configuration files for hosts which run a LXD-server.

• groups: we associate all lxd servers to the 'lxd'-group.
• required attributes:
  • bridge: the bridge network interface that is used.
• optional attributes: There are no optional attributes which would expand the configuration.
• gimmick attributes: There are no gimmick attributes we usually add for meta data.
• influenced by: the evaluation of the server_lxd-template influenced by
  • the ip4 and interface value of the host itself (etc/network/interfaces.normal.twig, etc/network/interfaces.lxd.twig)
  • the routers, netmask, domain, from the network.json-file (etc/network/interfaces.normal.twig, etc/network/interfaces.lxd.twig)
  • whether there are other dns servers inside the domain (etc/network/interfaces.normal.twig, etc/network/interfaces.lxd.twig)
  • whether the server is also a DHCP server. (etc/network/interfaces.normal.twig, etc/network/interfaces.lxd.twig)

server_ldap

Template for configuration files for hosts which run an OpenLDAP-server for the domain.

• groups: we associate all lxd servers to the 'ldap'-group.
• required attributes:
  • ldap: an array containing: (var/server_ldap/etc/default/slapd.twig, root/ldap/-folder)
  • name: either the hosts name or a cname the host is associated to.
  • password: the root password of the LDAP database.
  • user_pass: password for the user that is used during replication.
  • credentials: credential information used during replication. Example:

    "ldap": {
      "name": "ldap01",
      "password": "StandardPasswort4",
      "user_pass": "{SSHA}gZGsYQZW+p7asdfsdfsdfed3sM+1AWo+",
      "credentials": "vfSDAFdcg"
    }

• optional attributes: There are no optional attributes which would expand the configuration.
• gimmick attributes:
  • cnames: each ldap server in a domain gets a unique cname 'ldapXX'.
• influenced by: the evaluation of the server_ldap-template influenced by:
  • the used certificate (etc/ldap/ca-cert.pem, see: root/ldap)
  • it's own "ldap.name" (etc/default/slapd.twig)
  • whether the host is also a kerberos_client. (etc/default/slapd.twig)

server_nfs

Template for configuration files for hosts which run an NFS-Kernel-Server-server for the domain.

• groups: we associate all nfs servers to the 'nfs'-group.
• required attributes:
  • a shares array, where each entry inside the array stands for one share that is defined by:
  • path: the absolute path to the share
  • range: the ip range the share is available to
  • share: the absolute path to the share
  • target: the path where the share should be mounted under on clients
  • fid0: boolean, whether or not the share uses 'fsid=0'. Example:

    "shares": {
        "\/var\/nfs\/home": {
            "range": "10.4.0.0\/16",
            "share": "\/var\/nfs\/home",
            "target": "\/home"
        },
        "\/var\/machineshare": {
            "range": "10.5.0.0\/16",
            "share": "\/var\/machineshare",
            "target": "\/var\/nfs"
        }
    },

    Here we would share:

  • '/var/nfs/home' and clients inside the 10.4.0.0\/16 ip range will mount this share as their /home-folder.
  • '/var/machineshare' and clients inside the 10.5.0.0\/16 ip range will mount this share as their /var/nfs-folder.
• optional attributes: no optional attributes which would expand the configuration.
• gimmick attributes:
  • cnames: each nfs server in a domain gets a unique cname 'nfsXX'.
• influenced by: the evaluation of the server_nfs-template influenced by:
  • whether the nfs server itself is a 'kerberos_client' and thus uses kerberos as security base for the shares. (etc/exports.twig)
  • it's own "shares" array. (etc/exports.twig)
  • the current network domain from the network.json-file (etc/idmap.conf.twig)
  • the names of all host which are associated to the server- or client-template. (etc/idmap.conf.twig)

server_vbox

Template for configuration files for hosts which run a VirtualBox-server for the domain.

• required attributes:
  • vbox array containing:
    • home: absolute path to where the virtual machines are saved on the hdd.
    • backup: absolute path to where the virtual machines are backuped to.
    • iso: absolute path to where the iso-images for the virtual machines are stored. (can be empty)
    • sync_dirs: additional folders (relative to home) to backup Example:

      "vbox": {
      "home": "\/var\/virtualbox",
      "backup": "\/var\/backup\/virtualbox",
      "iso": "\/var\/iso-images",
      "sync_dirs": {
          "bin": true,
          "shared": true
      }
      },

      All the attributes inside the vbox-array are used inside the root/virtualbox-backup.php.twig.

• optional attributes: There are no optional attributes which would expand the configuration.
• gimmick attributes: There are no gimmick attributes we usually add for meta data.
• influenced by: the evaluation of the server_vbox-template is not influenced by other templates or attributes.

server_web

Template for configuration files for hosts which run a web-server inside the domain.

• groups: we don't add web servers to any specific group
• required attributes: There are no required attributes.
• optional attributes: There areno optional attributes which would expand the configuration.
• gimmick attributes: There are no gimmick attributes we usually add for meta data.
• influenced by: the evaluation of the server_web-template is not influenced by other templates or attributes.

server_samba_castle / server_samba_loft:

Template for configuration files for hosts which run a [SAMBA]()-server for the castle-domain.

• groups: we don't add samba servers to any specific group
• required attributes: no required attributes.
• optional attributes: no optional attributes which would expand the configuration.
• gimmick attributes: no gimmick attributes we usually add for meta data.
• influenced by: the evaluation of the serversamba(castle/loft)-template is not influenced by other templates or attributes.

Both templates are a bunch of static configuration files which cover the samba configuration and a bunch of incron.d jobs.

router_loft

Template of configuration files for routers which run for the loft-domain. The template mainly covers the firehol-, network/interfaces-configuration and the vpn-tunnel maintenance.

• groups: we don't add routers to any specific group.
• required attributes:
  • "ip4extern": the external public ip.
  • "route": an array containing:
  • "dmz_if": network interface for the DMZ.
  • "wan_if": network ingerdace for the private local network.
  • "nameserver": ip of the local nameserver to use.
  • "netmask": netmask of the local network.
  • "use_interface": name of the internet interface configuration to use.
  • inet_ifaces: array which configuration variables for the available internet connections
    • if: the interface the modem/router providing the internet connection is connected to
    • dhcp: whether the connected router also runs as a dhcp server.
    • address: the external public static ip the connected router/modem is associated with.
    • gateway: the gateway provided by the ISP for the connection. Example:

      "unitymedia": {
        "if": "enp3s2",
        "dhcp": false,
        "address": "123.123.123.123",
        "netmask": "255.255.255.252",
        "gateway": "123.123.123.226"
      },

  • tunnel array containing configuration data for our vpn tunnel.
  • tun_net: range of the net that we tunnel to.
  • short: shortname for the target network.
  • extern: public extern IP of the exposed host of the target network.
  • intern: private IP of the host of the target network (ip under which we can access the target once the tunnel is active).
  • local: subnet number of the current network (X in: 10.X. ...).
  • local: subnet number of the remote/target network (X in: 10.X. ...).
  • port: ssh port on which we access through the WAN. Example:

    "tunnel": {
        "castle": {
            "tun_net": "10.3.0.0\/16",
            "short": "csl",
            "extern": "80.152.14.226",
            "intern": "10.4.1.2",
            "local": "8",
            "to": "4",
            "port": "60022"
        }
    },

    (etc/cron.d/crontab-router.twig, etc/firehol/firehol.default, etc/network/interfaces.default.twig)

    • exposed: array containing configuration variables which define how to expose ports of to the world For each host with exposed ports we got one entry. Each entry inside the array contains the ip and which wan port gets exposed at which local port. Example:

      "exposed": {
        "server02": {
            "ip": "10.10.10.10",
            "ports": {
                "SSH": {
                    "loc": "22",
                    "wan": "22"
                },
                "TLS graph": {
                    "loc": "4339",
                    "wan": "4339"
                },
            }
        }
      }

      Here we expose two ports of server02 with ip '10.10.10.10'. a. the SSH port 22 to the external port 22 b. the TLS graph connection port 4339 to the external port 4339. (etc/firehol/firehol.default)

• optional attributes: There are no optional attributes which would expand the configuration.
• gimmick attributes: There are no gimmick attributes we usually add for meta data.
• influenced by: the evaluation of the router_loft-template is not influenced by other templates or attributes.

router_castle

Template for configuration files required for routers inside the castle-domain.

• groups: we don't add routers to any specific group.
• required attributes:
  • route: array which holds dnat, tunnel and interface information.
    • iff: a virtual internet interface name all internet interfaces are connected to.
    • local: local subnet number (10.X.) -> local subnet number X.
    • inet_ifaces: array containing data about each interface that is connected to a physical router/modem.
    • id: the id used to identify the connection in the routing tables.
    • description: description of the network connection.
    • if: physical interface to the router/modem.
    • ip: public IP of the interface.
    • net: network range of the connection.
    • netmask: netmask of the connection.
    • setgateway: whether to set the gateway inside /etc/network/interfaces.
    • gateway: gateway to set in /etc/network/interfaces for the connection.
    • mark the firewall mark (fwmark) to use.
    • bit used when marking packages inside the firewall rules. (currently commented out). Example:

      "adsl01": {
      "id": "202",
      "description": "(6mbit/600kbit)",
      "if": "enp2s0f0",
      "ip": "1.2.3.24",
      "net": "1.2.3.0/24",
      "netmask": "255.255.255.0",
      "gateway": "1.2.3.1",
      "mark": "0xe1",
      "bit": "0"
      }

  • tunnel: array containing data of potential tunnels to other networks.
    • remote: subnet number of the remote network
    • netmask: the netmask of the external network
    • device: name of the device used for tunneling
    • net: IP range of the remote network Example:

      "tunnel": {
        "loft": {
          "remote": "8",
          "netmask": "255.255.255.255",
          "device": "tun8",
          "net": "10.8.0.0/16"
        }
      },

  • dnat: array containing configuration data to expose/forward ports of other hosts.
    • ip: the local network ip of the host.
    • ports: array containing which ports on the router should be forwarded to which port on the exposed host.

      "dnat": {
      "tel01": {
        "ip": "10.4.10.1",
        "ports": {
          "HTTPS": {
            "from": "60443",
            "to": "443"
          }
        }
      }
      }
      }

• optional attributes: There are no optional attributes which would expand the configuration.
• gimmick attributes: There are no gimmick attributes we usually add for meta data.
• influenced by: the evaluation of the router_loft-template is not influenced by other templates or attributes.

kioskpi

Template for configuration files for our KioskPis.

• groups: we associate all kioskpis to the 'kiosk'-group.
• required attributes:
  • homepage: the URL the PI is controlled by.
• optional attributes: There are no optional attributes which would expand the configuration.
• gimmick attributes:
  • location where to find the KioskPi in the physical world.
• influenced by: the evaluation of the kioskpi-template is influenced by:
  • it's hostname (etc/hostname.twig, etc/hosts.twig*)
  • the chosen homepage (home/pi/kioskpi/index.html.twig)

lightpi

Template for configuration files for our LightPis.

• groups: we associate all lightpis to the 'lightpis' group.
• required attributes: There are no required attributes.
• optional attributes: There are no optional attributes which would expand the configuration.
• gimmick attributes: There are no gimmick attributes we usually add for meta data.
• influenced by: the evaluation of the lightpi-template is influenced by:
  • it's hostname (etc/hostname.twig, etc/hosts.twig*)