= Ansible

c3voc - configuration management

<code>
git clone git@git.c3voc.de:cm
cd ansible
vim README.md
</code>

**Public version of this repository:** [[https://github.com/voc/cm/tree/master/ansible#readme|https://github.com/voc/cm/ansible/]]

<panel type="danger" title="Outdated">This page is outdated. As of 2022-08-01, c3voc uses bundlewrap to deploy the room setups. Please follow the [[https://github.com/voc/cm/blob/master/bundlewrap/README.md|README inside the git repo]] to get started, or ask in #voc-lounge on hackint for support. The documentation below is only needed if you need to deploy one of the servers in a colo.</panel>


== README.md

=== Installation

To manage hosts with [[http://ansible.com/|ansible]] you need to install ansible > 2.3 on your machine.

See https://docs.ansible.com/ansible/intro_installation.html for instructions


=== Usage

Syntax validation.


  ansible-playbook -i inventory/event -l mixers site.yml --syntax-check

Basic ''ansible'' call to deploy new config to a specific host.

  ./ansible-playbook-keepass -u root -i inventory/event -l 192.168.122.1 site.yml

Basic ''ansible'' call to deploy new config to a set of hosts on an event.

  ./ansible-playbook-keepass -u voc --become --become-method=sudo -i inventory/event -l saal1 site.yml
  
  
Also have a look at the 'Usefull combinations' section of this page.

=== Keepass Password

In case you need to do a lot of playbook runs you can also set the password using the following although it is not recommended.

  export KEEPASS_PW='…'
  ./ansible-playbook-keepass … site.yml


=== Host notes

==== router.lan.c3voc.de

What you need:

* install plain debian
* setting hostname to ''router.lan.c3voc.de''
* make sure you have two network interfaces configured with names ''pbl'' (public) and ''int'' (internal)
* run ansible to deploy config


==== monitoring.lan.c3voc.de

You have to name the monitoring host ''monitoring.lan.c3voc.de''. After
deployment, you have to run ''check_mk -I && check_mk -O'' inventory each host.

=== TODO

Have a look into ''TODO'' file.

=== Docs

* ''ansible-doc -l'' lists all available modules
* ''ansible-doc $module'' opens a very helpful knowledge page for a given module
* [[http://docs.ansible.com/|Documentation Page]]


== Tags

=== Overview

^ Tag                       ^ Result                                                                                                    ^
| config                    | Only run configuration tasks like changing config files and reload daemon.                                |
| install                   | Run all needed tasks which needs to be run on a new and fresh installation.                               |
| deploy_website            | Deploy (git pull) streaming website and flush fcgi cache.                                                 |
| nginx                     | Run all nginx tasks.                                                                                      |
| icecast                   | Run all icecast tasks.                                                                                    |
| haproxy                   | Run all haproxy tasks.                                                                                    |
| ssh(d)                    | Run all sshd tasks.                                                                                       |
| user                      | Manage user.                                                                                              |
| encodermode               | Deploys event related config. Also can be used to change from sd-dvswitch to hd-direct or to hd-voctomix  |
| voctomix                  | Updates/regenerates all voctomix related files on the cube                                                |
| artwork                   | Deploy artwork (background, pause loop)                                                                   |
| ''checkout'' or ''pull''  | Get update subversion or git repository versions.                                                         |
| gpg                       | Update apt gpg key                                                                                        |
=== Useful combinations

  * Change ''nginx'' config on all relays: ''<nowiki>--tags nginx,config</nowiki>''
  * Deploy only streaming website: ''<nowiki>--tags deploy_website</nowiki>''
    * e.g. `./ansible-playbook-keepass --tags deploy_website -i event loadbalancers.yml`

  * Deploy encoder setting for a conference
    * edit group_vars/all  and group_vars/saal*
    *    `./ansible-playbook-keepass -i inventory/event --limit encoder1.lan.c3voc.de --tags encodermode site.yml`
    * or `./ansible-playbook-keepass -i inventory/event --limit encoder1.lan.c3voc.de --tags voctomix site.yml`
    * or `./ansible-playbook-keepass -i inventory/event  -l saal5 --tags voctomix site.yml`
 
  * Debug without rerunning working tasks
    * ```KEEPASS="${KEEPASS}" KEEPASS_PW="${KEEPASS_PW}" python3 `which ansible-playbook` -i inventory/event -l saal5 --tags voctomix --start-at-task="encoder : create recording script" encoder.yml```


== Variables in roles

=== Global usage
^ Variable  ^ Options             ^ Usage ^
^ Event ^^^
| event.acronym | String | |
| event.name | String | |
| event.slogen | String | |
| event.formats.hd | ''yes'' or ''no'' | |
| event.formats.sd | ''yes'' or ''no'' | |
| users | Array<Hash> | Group of users described as Array with hashes. Each user hash has to be defined with ''name'' and ''state'' keys. ''state'' could be ''present'' or ''absent''. Default definition is in ''group_vars/all''. |
^ Access ^^^
| trusted_ipv4_ips | Hash | Define trusted IPv4 addresses for usage in iptables rules. \\ Example: ''{ "comment": '0.0.0.0/0', … }'' |
| trusted_ipv6_ips | Hash | Define trusted IPv6 addresses for usage in iptables rules. \\ Example: ''{ "comment": '::/0', … }'' |

=== Relay
^ Variable  ^ Options             ^ Usage ^
| rtmp      | ''yes'' or ''no''  | Configure nginx with rtmp support. |
| hidden    | ''yes'' or ''no''  | Configure iptables to allow only access for IPs defined in ''trusted_ipv6_ips'' and trusted_ipv4_ips to the system. Default is ''no''. |
^ nginx                           ^^^
| nginx_worker_processes | Fixnum | Equivalent to nginx ''worker_processes'' option to define number of nginx worker. Default: ''2'' |
| nginx_worker_connections | Fixnum | Comparable to nginx ''worker_connections'' to define max connections per process worker. Default: ''4096'' |
| nginx_bind_ipv6 | String | Bind nginx to a specific IPv4 address. Required ''nginx_bind_ipv4''. |
| nginx_bind_ipv4 | String | Bind nginx to a specific IPv6 address. Required ''nginx_bind_ipv6''. | 
| nginx_streaming_locations | Hash | Define nginx-rtmp mount points to pull rtmp streams from remote server. Only useful with ''rtmp=yes''. \\ Example: ''{ 's1': 'ip1', 's2': 'ip2', … }'' |
| nginx_hls_relive_masters | Array | Configure relive upstream servers. |
| nginx_hls_relive_masters_backup | Array | Configure backup server for nginx relive upstreams.  | 
| nginx_hls_masters | Array | Configure HLS master upstream servers. |
| nginx_hls_masters_backup | Array | Configure backup HLS master upstream servers. |
| nginx_hls_relive_cache_max_size | String | Default: ''200g'' | 
| nginx_hls_cache_max_size | String | Default: ''30g'' | 
^ Icecast2                           ^^^
| icecast | ''yes'' or ''no'' | Enable icecast. |
| icecast_fix_mount_metadata | Array<Hash> | Example: ''[{ "mount-name": "/example.opus", "type": "audio/ogg" }, …]'' |
| icecast_additional_mounts | Array<Hash> | Example: ''[{ "mount-name": '/lounge.mp3',  "type": '…', "username": 'source',  "password": '…',    "stream-name": "…",   "dump-file": "/srv/icecastdumps/lounge-%F_%H-%M-%S_%s.mp3" }, …]''|
| icecast_static_streams_meta_data | | |
| icecast_admin_user | String | |
| icecast_admin_password | String | |
| icecast_source_password | String | |
| icecast_relay_password | String | |
| icecast_master_password | String | |
| icecast_admin_email | String | | 
| icecast_relay_on_demand | Fixnum | Default: ''0'' |
| icecast_push_master | ''yes'' or ''no'' | Configure additional mount mounts described in  ''icecast_additional_mounts''. |
 
=== Loadbalancer

^ Variable  ^ Options             ^ Usage ^
| haproxy_nbproc | Fixnum |  | 
| nginx    | ''yes'' or ''no''  | Install and configure nginx for streaming website. Default: ''no''      |
| php      | ''yes'' or ''no''  | Install and configure php-fpm and deploy streaming website. Default: ''no'' |

=== ssh_server

^ Variable  ^ Options             ^ Usage ^
| ssh_allow_voc_password_login    | ''yes'' or ''no''  | Allow password login in local network. Default: ''no''      |


=== CRS-Worker

^ Variable  ^ Options     ^ Usage ^
| crs_token    | String  | Define crs token from [[c3tracker]].     |
| crs_secret   | String  | Define crs secret specified by [[c3tracker]].  |


=== Monitoring client and server

^ Variable  ^ Options     ^ Usage ^
| monitoring.collectd_server    | String  |      |
| monitoring.collectd_username   | String  |   |
| monitoring.collectd_password    | String  |      |
| monitoring.collectd_interval    | Fixnum  | Default: ''30''     |


=== Encoder mode
Ansible can deploy [[hardware:encoder|Encoder-Cubes]] and [[hardware:mixer|Mixer-Notebooks]] with one of three modes:
  * **sd-dvswitch** was the Default until mid-2016. It runs a mixing-chain around dvswitch and produces sd-video in .dv-files
  * **hd-direct** is more or less what was running on *C3. It only configures the encoder (doesn't need the mixer) and records / streams directly of one of the two decklink mini-recorders in an encoder. It needs a Hardware SDI-Distribution to allow streaming **and** recording
  * **hd-voctomix** is the new and all-shiny videomixer, running voctocore and sources/sinks on the encoder and voctogui on the mixer

Ansible can transition between all three modes. All three systems are always configured and prepared.
Which one should be running can be configured with the ''encodermode'' variable in the ''saal[1-6]'' groupvars file.
Changing that and running ansible with the encodermode-Tag (or without any tag) stops the unnecessary Tasks and starts the required ones. It allows transitioning between dvswitch and voctomix within a minute.


=== Other

…