Metadata-Version: 1.2
Name: hostlist
Version: 1.3.1
Summary: Sync hostlist and builds config files for services.
Home-page: https://github.com/particlekit/hostlist
License: UNKNOWN
Author: Robin Roth
Author-email: robin.roth@kit.edu
Requires-Python: >=3.2
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: System :: Systems Administration
Requires-Dist: PyYAML
Requires-Dist: termcolor
Requires-Dist: requests
Requires-Dist: cherrypy
Requires-Dist: GitPython

hostlist
========

Hostlist reads yaml lists with information about hosts and generates
config files and inventory for several services.


Quickstart
----------

Example input files are in the ``tests`` directory. Hostlists are defined in the ``hostslists`` subdirectory, where the filename
encodes the ``hosttype`` and ``institute`` attributes of the contained hosts.

Run ``buildfiles`` to generate the output.
``buildfiles --help`` shows the available options.

Configuration
-------------

The main configuration is in ``config.yml`` in the working directory. 
Hostlists are collected in a directory listed in ``config.yml``.


Format of hostlists
-------------------

The hostlists are files under ``hostlists``. The file format is either
``hosttype-institute.yml`` or ``hosttype.yml``, i.e. 0 or 1 dash. The filename will
be parsed and set as institute/hosttype for all hosts in that file.

The hostlists are in yaml. Multiple yaml documents in one file are allows. Each
yaml document starts with a line containing only ``---``.

Each yaml document document has a ``header`` and a list of ``hosts``.
The header has to have an iprange, that lists the allowed range for the hosts in
the file. It can also set variables and groups.

The hostlist is a list of dicts, which each need a hostname and an ip and can
take other variables.

Variables and Groups
--------------------

Each host has a list of variables (dict) associated with it as well as a list of groups (set).

If variables are set in multiple places they are overwritten in this order:
filename < header < host

For groups a default is set in the config file. 
In the header and the host definition one can define lists ``groups`` and ``notgroups`` that are added/subtracted from the list of
groups for that host.

Groups are used to define which hosts are used in some outputs (muninnode, ssh_known_hosts) or which hosts should be included for
checks (needs_ip, needs_mac).


Checks
------

Many checks are performed to ensure consistency and find mistakes before they
are deployed:

* IP range

  * hosts must have an IP in the given range
  * all hosts must fall into the IP ranges stated in the config
  * ipranges between files must not overlap (except iprange_allow_overlap is set)
  
* IP, MAC and hostname must be unique
* if ``user`` is set, it must be an existing user account (to detect machines
  belonging to users who no longer have an account)
* if ``end_date`` is set, it must be in the future


Services
--------

At the moment the supported services are:

* /etc/hosts, can also be used for dnsmasq
* dhcpd
* ansible inventory
* munin 
* ssh_known_hosts generation


Web daemon
----------

You can start ``hostlist-daemon`` to serve the generated content via http. Start ``hostlist-daemon`` where you would run ``buildfiles``.
The daemon is based on cherrypy and has a config file daemon.conf. 


Example
-------

A working example for inputs and all configuration files can be found in ``tests``.


DNSVS Synchronization
---------------------

Besides generating config files, the hostlist can also be synchronized against
DNSVS, which is the dns management system used by https://www.scc.kit.edu.

In order to use the DNSVS interface you need a ssl-key, which is expected in ~/.ssl/net-webapi.key. In order to generate the key, follow the instructions in the section "Hinweise zur Zertifikatsbenutzung bzw. Registrierung" at the bottom of the page https://www-net-doku.scc.kit.edu/webapi/2.0/intro.

With the key added, you can run ``buildfiles``, which shows you a
diff between dnsvs and the local files and gives the option to copy the local
hostlist to dnsvs.


Tests
-----
To run the tests:
::

  cd tests; py.test

Contribute
----------
Feel free to use the code and adjust it to your needs.
Pull requests are welcome!

Style guide
-----------

The code should obey PEP8 (as enforced by flake8 or pylint) when possible.

