Upgrade notes

This document contains information and notes about any changes that are required in the Ansible inventory or the IT infrastructure managed by DebOps to perform the upgrades between different stable releases.

Unreleased

v3.3.0 (2026-03-13)

No significant changes which require a manual intervention.

v3.2.0 (2024-09-16)

No significant changes which require a manual intervention.

v3.1.0 (2023-11-29)

Changes in inventory variables

• The debops.dropbear_initramfs role renamed the dropbear_initramfs__*_authorized_keys keys according to the ansible.posix.authorized_key module. Variable dropbear_initramfs__authorized_keys_options has also been renamed to dropbear_initramfs__authorized_keys_key_options.

• The debops.sshd role was refreshed and multiple variables related to the contents of the /etc/ssh/sshd_config configuration file were removed. Their values are now managed using Universal Configuration. In the process, some of the configuration options will use their default values from Debian or upstream. List of removed default variables:

  • sshd__listen

  • sshd__banner

  • sshd__log_level

  • sshd__accept_env

  • sshd__x11_forwarding

  • sshd__permit_root_login

  • sshd__password_authentication

  • sshd__compression

  • sshd__use_dns

  • sshd__max_auth_tries

  • sshd__max_sessions

  • sshd__max_startups

  • sshd__login_grace_time

  • sshd__client_alive_count_max

  • sshd__privilege_separation

  • sshd__custom_options

  • sshd__default_allow_groups

  • sshd__allow_groups

  • sshd__group_allow_groups

  • sshd__host_allow_groups

  • sshd__authorized_keys

  • sshd__authorized_keys_system

  • sshd__authorized_keys_user

  • sshd__match_list

  • sshd__match_group_sftponly

• The debops.apt role has been refreshed and some variables changed their data structures:

  • apt__sources, apt__group_sources, apt__host_sources, apt__combined_sources

  • apt__repositories, apt__group_repositories, apt__host_repositories

  • apt__keys, apt__group_keys, apt__host_keys

  Some of the role variables were also removed:

  • apt__sources_deploy_state (replaced with apt__deploy_state)

  • apt__sources_filter_duplicates

  • apt__source_types (replaced with apt__archive_types)

  • apt__remove_default_configuration

  • apt__install_recommends

  • apt__install_suggests

  • apt__deb822_*_repositories

  • apt__conf (replaced with apt__configuration)

  • apt__group_conf (replaced with apt__group_configuration)

  • apt__host_conf (replaced with apt__host_configuration)

  • apt__distribution_release_map

  • apt__distribution_suite_map

  • apt__distribution_suite

  • apt__distribution_suffix_map

  • apt__distribution_suffixes

  • apt__distribution_components_free

  • apt__distribution_components_nonfree

  • apt__distribution_components

  • apt__archive_source_map

  • apt__archive_source

  • apt__original_sources

  • apt__default_sources

  • apt__default_sources_state

  • apt__security_sources_state

  • apt__security_sources

  • apt__group_security_sources

  • apt__host_security_sources

• THe debops.docker_server role has been redesigned, many variables have been removed and are no longer needed. Check the role documentation for details.

v3.0.0 (2022-02-17)

Changes in the OpenLDAP support

• In the debops.slapd role, the mailservice.schema LDAP schema includes two new LDAP attributes, mailPrivateAddress and mailContactAddress. The server will enforce the mailPrivateAddress attribute to be unique and that all its values are also included in the mail attribute.

  The above constraints result in the role not working correctly when the new mailservice.schema is not applied in the OpenLDAP service. The role cannot "re-apply" an already installed LDAP schema, therefore the service needs to be rebuilt for the new changes to take effect. Refer to the Backup and restore procedures documentation for help with rebuilding the directory.

Redesign of the Debian Pressed support

• The debops.preseed role has been redesigned from the ground up. Most of the variables related to preseed.cfg and postinst.sh file contents have been removed and role now uses Universal Configuration system to manage the contents of these files. You should check the new role defaults and documentation to see how Preseed configuration is implemented.

• Support for installation and configuration of Salt Minions during provisioning has been removed from the postinst.sh scripts. Basic installation can be implemented uding postinst commands; if there's a demand for fully-fledged support it can be brought back.

• Access controls using debops.nginx role access policy functionality has been removed. If needed, access control can be implemented using firewall rules to restrict access to the Preseed server to selected subnets.

• The role no longer creates separate UNIX group and account for Preseed configuration files published by the webserver. The files are owned by the root UNIX account, with www-data group having read-only access.

• Location of the generated Preseed files has been changed to conform better to best practices used in DebOps; files will be stored in the /srv/www/sites/debian-preseed/public/ directory by default.

• The names of the nginx configuration files have been changed; they are no longer based on the DNS domain used by Preseed but use static filenames. In the existing installations, the old configuration files might need to be removed manually to avoid conflicts with new configuration.

• The postinst.sh scripts have been greatly simplified and no longer contain code that creates custom UNIX accounts and configures grub directly. These functionalities have been delegated to the Debian Installer and are used through the Preseed configuration files.

Changes in inventory variables

• In the debops.nginx role one variable was removed:

  Old variable name	New variable name	Changed value
  nginx_enable_sdpy	Removed	No

Icinga Director database migrations

• After debops.icinga_web updates the Icinga Director module, you will have to perform a quick database migration to get Director to work again. Just click the database migration button on the 'Icinga Director' -> 'Activities log' page.

v2.3.0 (2021-06-04)

Redesigned authorized_keys role

• The debops.authorized_keys role has been redesigned, here are changes in the Ansible inventory variables used by the role:

  Old variable name	New variable name	Changed value
  authorized_keys__readonly	Removed	No
  authorized_keys__options_map	Removed	No
  authorized_keys__default_options	Removed	No
  authorized_keys__force_options	Removed	No
  authorized_keys__list	authorized_keys__identities	Yes
  authorized_keys__group_list	authorized_keys__group_identities	Yes
  authorized_keys__host_list	authorized_keys__host_identities	Yes
  authorized_keys__dependent_list	authorized_keys__dependent_identities	Yes

v2.2.0 (2021-01-31)

Changes in the NetBox role

• netbox__config_webhooks_enabled has been removed upstream. No further action other than removing the variable from your inventory should be needed. See Require running the rq-worker process.

Changes to debops.resolvconf facts

• The 'domain', 'nameservers' and 'search' variables have been removed from the resolvconf Ansible local facts script. You are encouraged to use the ansible_domain, ansible_dns.nameservers and ansible_dns.search variables instead.

Splitting up debops.dhcpd

• A new role has been written for the ISC DHCP Relay Agent: debops.dhcrelay. dhcrelay was originally part of the debops.dhcpd role. You will need to update your Ansible inventory by adding your dhcrelay hosts to the new debops_service_dhcrelay group. Inventory variable changes are as follows:

  Old variable name	New variable name	Changed value
  dhcpd_relay_servers	dhcrelay__servers	No
  dhcpd_relay_interfaces	dhcrelay__interfaces	No
  dhcpd_relay_options	dhcrelay__options	Yes

Changes in the OpenLDAP support

• The list of the OpenLDAP overlays configured by the debops.slapd role has been modified. This change cannot be applied cleanly on an existing OpenLDAP server and will require re-initialization of the service - an easiest way is reinstallation of the host and import of the existing directory. Check the Backup and restore procedures documentation for more details and restore instructions.

• The mailservice.schema and the eduperson.schema LDAP schemas have been modified. Changes will not be applied automatically on existing installations and it is recommended to re-create the directory from scratch to apply new schema cleanly.

• Some variables in the debops.slapd role have been modified:

  Old variable name	New variable name	Changed value
  slapd__slapacl_test_rdn_map	slapd__slapacl_default_tasks	Yes, a list

ISC DHCP Server role rewrite

• The debops.dhcpd role has been largely rewritten in order to better support dual stack networking and to modernize many aspects of the role.

• Support for managing the ISC DHCP Relay Agent has been moved to the debops.dhcrelay role.

• dhcpd_* inventory variables have been renamed to dhcpd__*. Other inventory variable changes are:

  Old variable name	New variable name	Changed value
  dhcpd_mode	Removed
  dhcpd_ipversion	Removed
  dhcpd_server_options	dhcpd__options	No
  dhcpd_interfaces	dhcpd__interfacesv4 and dhcpd__interfacesv6	No
  dhcpd_lease_time	Removed
  dhcpd_global_default_lease_time	dhcpd__default_lease_time	Yes
  dhcpd_global_max_lease_time	dhcpd__max_lease_time	Yes
  dhcpd_auto_options	Removed
  dhcpd_nameservers	dhcpd__domain_servers	Yes
  dhcpd_options	dhcpd__global_options_map	Yes
  dhcpd_subnets	dhcpd__subnets	Yes
  dhcpd_subnet_default	dhcpd__default_subnets	Yes
  dhcpd_includes	Removed

Changes in debops.lvm

• Changed default behaviour: the role now mounts LVM volumes even when item.fs is not defined. This of course still requires setting the mount point with item.mount.

v2.1.0 (2020-06-21)

Inventory variable changes

• Some variables in the debops.ntp role have been removed:

  Old variable name	New variable name	Changed value
  ntp__timezone	tzdata__timezone	No

v2.0.0 (2020-01-30)

General

• Official DebOps roles have been renamed and the debops. prefix has been dropped from the directory names. The custom playbooks and role dependencies that use DebOps roles will have to be updated accordingly to function correctly again.

• The variables in various roles that hold the automatically generated passwords stored in the secret/ directory have been modified to use the inventory_hostname variable instead of the ansible_fqdn variable as a part of the path to the password file. The roles where these changes happened are:

  • debops.apt_cacher_ng

  • debops.librenms

  • debops.mailman

  • debops.nginx

  • debops.owncloud

  • debops.phpipam

  • debops.postgresql_server

  • debops.preseed

  • debops.roundcube

  These changes will result in existing passwords or other generated data being automatically regenerated by Ansible on the next run of a given role. This might affect access to the services from other hosts if the new passwords are not applied everywhere. Make sure to re-run the affected roles on all relevant hosts in your infrastructure to update the passwords where necessary.

LDAP

• The values of the authorizedService and host LDAP attributes expected by various DebOps roles have been changed. You will need to update your LDAP directory entries for the new values to take effect before applying these changes to the remote hosts, otherwise users and services might stop working correctly.

  Changes in the authorizedService attribute:

  Old value	New value	Notes
  *	all	Grants access to all services
  web-public	web:public	Grants access to publicly-reachable web services
  None	shell	Grants access to UNIX environment over SSH protocol

  Changes in the host attribute:

  Old value	New value	Notes
  *	posix:all	Grants access to POSIX environment on all hosts
  <fqdn>	posix:<fqdn>	Grants access to POSIX environment on a specific host based on its FQDN
  *.<domain>	posix:*.<domain>	Grants access to POSIX environment on a specific host based on its domain
  <hostname>	Removed	This scheme has been replaced by a more general purpose "URN-like" scheme. See Host-based access control for more details.

Inventory variable changes

• Some variables in the debops.docker_server role have been renamed:

  Old variable name	New variable name	Changed value
  docker_server__graph	docker_server__data_root	No

• A few of the default variables in the debops.dovecot role have been renamed. Additionally some variables related to the Sieve plugin configuration also changed:

  Old variable name	New variable name	Changed value
  dovecot_ssl_protocols	dovecot_ssl_min_protocol	No
  dovecot_firewall	Removed, see "Firewall configuration"	No
  dovecot_mail_location	dovecot_mail_location	Yes
  dovecot_sieve	dovecot_sieve_active_script	No
  dovecot_managesieve_config_map	dovecot_managesieve_config_map	Yes
  dovecot_lda_config_map	dovecot_lda_config_map	Yes

• Some of the variables in the debops.roundcube role have been renamed:

  Old variable name	New variable name	Changed value
  roundcube__default_host	roundcube__imap_server	No
  roundcube__domain	roundcube__fqdn	Yes, a string
  roundcube__local_config_map	roundcube__configuration	Yes
  roundcube__group_local_config_map	roundcube__group_configuration	Yes
  roundcube__host_local_config_map	roundcube__host_configuration	Yes
  roundcube__git_dest	roundcube__git_dir	No
  roundcube__git_checkout	roundcube__git_dest	No
  roundcube__default_plugins	The same	Yes, check variable

  Due to the change in the installation method, the Roundcube installation needs to be done from scratch. Before the role can work correctly, you should remove (or move aside) the source and installation directories. In the default setup you can run on a host:

  rm -rf /srv/www/sites/roundcube/public /usr/local/src/roundcube
  

  This will remove the installation and source directories, after which the role should be able to install Roundcube without issues. Remember to create backups in case of errors, especially if you use the SQLite database as backend since by default it is located inside of the installation directory.

v1.2.0 (2019-12-01)

Role configuration changes

• In the debops.dnsmasq role, dnsmasq__interfaces variable configuration, the router_enabled parameter has been renamed to the router_state parameter, with changed value type.

• In the debops.golang role, the golang__*_packages variables are used to define Go packages instead of simple list of APT packages, with entirely new syntax. Existing roles that rely on these variables might need to be updated. See the golang__packages documentation for more details.

Inventory variable changes

• The debops.gitlab role has an improved LDAP support that uses the debops.ldap role infrastructure. Due to that, some of the default variables have been changed:

  Old variable name	New variable name	Changed value
  gitlab_ldap_activedirectory	gitlab__ldap_activedirectory	No
  gitlab_ldap_enable	gitlab__ldap_enabled	No
  gitlab_ldap_basedn	gitlab__ldap_base_dn	Yes
  gitlab_ldap_binddn	gitlab__ldap_binddn	Yes
  gitlab_ldap_domain	Removed	No
  gitlab_ldap_host	gitlab__ldap_host	No
  gitlab_ldap_label	gitlab__ldap_label	No
  gitlab_ldap_manage	Removed	No
  gitlab_ldap_method	gitlab__ldap_encryption	Yes
  gitlab_ldap_password	gitlab__ldap_bindpw	Yes
  gitlab_ldap_password_file	Removed	No
  gitlab_ldap_port	gitlab__ldap_port	No
  gitlab_ldap_uid	gitlab__ldap_account_attribute	Yes

  The location of the GitLab LDAP account object in the LDAP directory tree as well as the object class and its attributes has been changed, see the debops.gitlab LDAP DIT documentation page for more details.

  Some of the default configuration options have been changed to better integrate GitLab with the LDAP environment managed by DebOps:

  Variable name	Old value	New value
  gitlab__ldap_user_filter	not defined	too large; see the variable
  gitlab__ldap_label	ldap.{{ ansible_domain }}	LDAP

• The debops.owncloud role has an improved LDAP support that uses the debops.ldap role infrastructure. Due to that, some of the default variables have been changed:

  Old variable name	New variable name	Changed value
  owncloud__ldap_create_user	Removed	No
  owncloud__ldap_domain	Removed	No
  owncloud__ldap_basedn	owncloud__ldap_base_dn	Yes
  owncloud__ldap_conf_map	owncloud__ldap_default_config	Yes
  owncloud__ldap_host	owncloud__ldap_primary_server	Yes
  owncloud__ldap_password	owncloud__ldap_bindpw	Yes
  owncloud__ldap_password_file	Removed	No

  The location of the Nextcloud LDAP account object in the LDAP directory tree as well as the object class and its attributes has been changed, see the debops.owncloud LDAP DIT documentation page for more details.

  The default connection method used by Nextcloud to connect to the LDAP directory has been changed from ssl to tls.

  The LDAP configuration method was rewritten and now uses custom DebOps filter plugins to allow merging of configuration from the role defaults and inventory variables. See owncloud__ldap_config for more details.

  Some of the default configuration options have been changed to better integrate Nextcloud with the LDAP environment managed by DebOps:

  Variable name	Old value New value
  owncloud__ldap_login_filter	(&(|(objectclass=inetOrgPerson))(uid=%uid))	too large; see the variable
  owncloud__ldap_group_filter	(&(|(objectclass=posixGroup)))	too large; see the variable
  owncloud__ldap_group_assoc_attribute	memberUid	member

  Support for the memberOf overlay has also been enabled by default, since the overlay is included in debops.slapd role.

• In the debops.ferm role, some of the connection tracking parameters have been renamed:

  Old parameter name	New parameter name	Changed value
  item.active_target	item.tracking_active_target	No
  item.invalid_target	item.tracking_invalid_target	No
  item.module	item.tracking_module	No

  See The 'connection_tracking' type for more details about connection tracking.

v1.1.0 (2019-08-25)

GPG key management changes

The debops.keyring centralizes management of the APT keyring and various GPG keyrings in unprivileged UNIX accounts. Various DebOps roles have been modified to use this role instead of performing the GPG key management on their own. If you use custom Ansible playbooks with these roles, you will need to update them to include the debops.keyring role.

List of modified DebOps roles:

• debops.ansible

• debops.cran

• debops.docker_registry

• debops.docker_server

• debops.elastic_co

• debops.gitlab_runner

• debops.hashicorp

• debops.hwraid

• debops.icinga

• debops.mariadb

• debops.mariadb_server

• debops.mosquitto

• debops.nginx

• debops.nodejs

• debops.owncloud

• debops.php

• debops.postgresql

• debops.postgresql_server

• debops.rstudio_server

• debops.salt

• debops.yadm

• debops-contrib.bitcoind

• debops-contrib.neurodebian

• debops-contrib.x2go_server

NodeJS and NPM changes

• By default, the debops.nodejs role will install the NodeJS and NPM packages from the OS (Debian or Ubuntu) repositories. On the Debian Oldstable release (currently Stretch), the packages backported from the Stable release will be used. The role supports an automatic upgrade to the upstream NodeJS package when the support for NodeSource repositories is enabled using the nodejs__node_upstream variable.

  On existing installations, status of the upstream APT repository should be preserved, however note that the Ansible local fact name that tracks this has been changed to ansible_local.nodejs.node_upstream, along with the default variable name. You might want to update the Ansible inventory to reflect the desired status of the NodeJS and NPM upstream support.

Inventory variable changes

• The debops.rsnapshot role has been redesigned and all of its rsnapshot_* variables have been renamed to rsnapshot__* to contain them in their own namespace. You will have to update your inventory.

  The configuration of the hosts to back up has also been redesigned; the role does not use Ansible inventory groups to define the hosts to back up implicitly; you now have to explicitly specify hosts to back up using the rsnapshot__hosts variables. There is a way to replicate the previous usage of inventory groups to define hosts to back up as well, see the provided examples.

• The debops.docker role has been renamed to debops.docker_server. The docker__* variables have been renamed to docker_server__*. You will have to update your inventory variables and move all hosts to the new inventory group [debops_service_docker_server] to continue using this role.

  Also, the Docker server no longer listens on a TCP port by default, even if debops.pki is enabled. You must set docker_server__tcp to True and configure an IP address whitelist in docker_server__tcp_allow if you want to connect to the Docker server over a network. It is recommended to use debops.pki to secure the connection with TLS.

• The debops.lxc role uses different names of the container configuration options depending on the LXC version used on the host. The name parameters used in the configuration might change unexpectedly between LXC versions, which might lead to wrong configuration entries being merged and broken LXC configuration.

  If you have configured lxc__configuration variables in the Ansible inventory, review them before applying the role configuration on LXC hosts. You can check the lxc__default_configuration variable to see which name parameters can change.

• The lxc__net_interface_fqdn variable has been renamed to lxc__net_fqdn to conform to the variable naming scheme for domain and FQDN names used in different DebOps roles. The new variable defines the FQDN name of the lxcbr0 interface. The lxc__net_domain variable which has done that previously is now used to define the DNS domain for the internal LXC subnet, and the new lxc__net_base_domain variable defines the base DNS domain for the lxc. subdomain.

• The debops.ipxe role default variables have been renamed to move them to their own ipxe__* namespace; you will have to update the Ansible inventory.

• The core__keyserver variable and its corresponding local fact have been replaced by the keyring__keyserver with a corresponding local fact.

• The debops.nginx role no longer defaults to limiting the allowed HTTP request methods to GET, HEAD and POST on PHP-enabled websites. Use the item.php_limit_except parameter if you want to keep limiting the request methods.

• The nodejs__upstream* variables in the debops.nodejs role have been renamed to nodejs__node_upstream* to better indicate their purpose and differentiate them from the nodejs__yarn_upstream* variables.

• The dokuwiki__main_domain variable has been renamed to dokuwiki__fqdn to fit the naming scheme in other DebOps roles.

v1.0.0 (2019-05-22)

Redesigned OpenLDAP support

• The debops.slapd role has been redesigned from the ground up, everything is new. Existing OpenLDAP servers/clusters will break if the new role is applied on them, don't do it. Set up a new OpenLDAP server/cluster and import the LDAP directory afterwards. See the role documentation for more details.

Changes to the UNIX group and account management

• The debops.users Ansible role has been modernized and it now uses the custom Ansible filter plugins included in DebOps to manage the UNIX groups and accounts. The group and account management now uses the same merged list of entries, which means that two new parameters have been added to control when groups or accounts are created/removed. You might need to update your inventory configuration if you use the role to create UNIX groups without corresponding accounts, or you put UNIX accounts in shared primary groups.

  By default, debops.users will create user private groups if item.group parameter is not specified; if you want to add accounts to the users primary group, you need to specify it explicitly.

  The user parameter can be used to disable the account management, so that only UNIX group is created. The private_group parameter controls the management of the UNIX group for a given configuration entry. See the role documentation for more details.

• The users__default_system variable has been removed from the debops.users role. The UNIX groups and accounts created by the role on hosts with the LDAP support will be normal accounts, not "system" accounts, and will use UID/GID >= 1000. This can be controlled per-user/per-group using the item.system parameter.

• The item.createhome parameter has been renamed to item.create_home in accordance with the renamed parameter of the user Ansible module.

• The users__resources, users__group_resources and users__host_resources variables have been removed. Their functionality has been reimplemented as the item.resources parameter of the users__*_accounts variables. See the role documentation for more details.

• The management of the admin accounts has been removed from the debops.users role and is now done in the debops.system_users role. See the system_users__default_accounts for a list of the default admin accounts created on the remote hosts.

Inventory variable changes

• The debops.phpipam has been refactored. Now the variables have been renamed from phpipam_* to phpipam__*

• The debops.auth default variables related to LDAP client configuration have been removed; the functionality is now managed by the debops.ldap, debops.nslcd and debops.nsswitch Ansible roles. The table below shows the old variable names and their new equivalents:

  Old variable name	New variable name	Changed value
  auth_ldap_conf	ldap__enabled	False by default
  auth_ldap_conf_domain	ldap__domain	No
  auth_ldap_conf_hostdn	Removed	No
  auth_ldap_conf_uri	ldap__servers_uri	Based on DNS SRV records
  auth_ldap_conf_tls_cacert	Removed	In ldap__default_configuration
  auth_ldap_conf_tls_reqcert	Removed	In ldap__default_configuration
  auth_ldap_conf_options	Removed	In ldap__default_configuration
  auth_nsswitch	Removed	Replaced by debops.nsswitch
  auth_nslcd_conf	Removed	Replaced by debops.nslcd
  auth_nslcd_domain	Removed	No
  auth_nslcd_ldap_server	Removed	No
  auth_nslcd_uri	Removed	In nslcd__default_configuration
  auth_nslcd_base	nslcd__ldap_base_dn	Based on debops.ldap facts
  auth_nslcd_tls_reqcert	Removed	In nslcd__default_configuration
  auth_nslcd_tls_cacertfile	Removed	In nslcd__default_configuration
  auth_nslcd_bind_host_basedn	nslcd__ldap_device_dn	Based on debops.ldap facts
  auth_nslcd_bind_host_cn	nslcd__ldap_self_rdn	Yes, different attribute, different value source
  auth_nslcd_bind_host_dn	nslcd__ldap_binddn	No
  auth_nslcd_bind_host_basepw	nslcd__ldap_bindpw	No
  auth_nslcd_bind_host_password	Removed	No
  auth_nslcd_bind_host_hash	Removed	No
  auth_nslcd_password_length	Removed	No
  auth_nslcd_options	Removed	No
  auth_nslcd_nss_min_uid	Removed	In nslcd__default_configuration
  auth_pam_mkhomedir_umask	nslcd__mkhomedir_umask	No
  auth_nslcd_pam_authz_search	Removed	No
  auth_nslcd_pam_authz_search_host	Removed	No
  auth_nslcd_pam_authz_search_service	Removed	No
  auth_nslcd_pam_authz_search_host_and_service	Removed	No

• The sshd__default_allow_groups default variable has been changed to an empty list. The group-based access control has been moved to a PAM access control rules defined in the sshd__pam_access__dependent_rules variable.

  Access to the OpenSSH service by the admins, sshusers and sftponly UNIX groups members should work the same as before. Access to the root account has been limited to hosts in the same DNS domain. UNIX accounts not in the aforementioned UNIX groups can access the OpenSSH service from hosts in the same DNS domain (other restrictions like public key presence still apply). See debops.pam_access documentation for more details about defining the PAM access rules.

• The default variables in the debops.sshd role related to LDAP support have been modified:

  Old variable name	New variable name	Changed value
  sshd__authorized_keys_lookup	Not modified	Based on debops.ldap facts
  sshd__authorized_keys_lookup_user	Not modified	Yes, to sshd
  sshd__authorized_keys_lookup_group	Removed	No
  sshd__authorized_keys_lookup_home	Removed	No
  sshd__authorized_keys_lookup_type	Not modified	Yes, sss included by default
  sshd__ldap_domain	Removed	No
  sshd__ldap_base	sshd__ldap_base_dn	Based on debops.ldap facts
  sshd__ldap_bind_basedn	sshd__ldap_device_dn	Based on debops.ldap facts
  sshd__ldap_bind_cn	sshd__ldap_self_rdn	Yes, different attribute, different value source
  sshd__ldap_bind_dn	sshd__ldap_binddn	Yes
  sshd__ldap_bind_bind_pw	sshd__ldap_bindpw	Yes, different password path
  sshd__ldap_bind_basepw	Removed	No
  sshd__ldap_password_length	Removed	No

• The management of the root account dotfiles has been removed from the debops.users role and is now included in the debops.root_account role. The dotfiles are managed using yadm script, installed by the debops.yadm role. The users__root_accounts list has been removed.

v0.8.1 (2019-02-02)

Subordinate UID/GID ranges for root

• The debops.root_account role will register a set of UID/GID ranges for the root account in the /etc/subuid and /etc/subgid databases. Depending on the OS distribution and release, these databases might contain existing UID/GID ranges which might interfere with the default set of 100000-165536 UID/GID range selected for the root account.

  In that case you should either disable this functionality, or recreate the host, at which point the UID/GID ranges for root will be reserved first, and any new accounts created by the system will use subsequent UIDs/GIDs. You can also update the UID/GID ranges manually, or select different UID/GID ranges for the root account in the role defaults.

Changes to Redis support in GitLab

• The Redis support has been removed from the debops.gitlab playbook. Since GitLab still requires Redis to work properly, you need to enable debops.redis_server role explicitly for the GitLab host. GitLab installation instructions have been updated to reflect this fact.

• To manage Redis on existing GitLab installations, you should enable the debops.redis_server role on them and run the Redis and GitLab playbooks afterwards. The existing Redis instance will be stopped and new Redis instance will be set up, with the same TCP port and password. Since the database will be empty, Gitaly service might stop working. After running the Redis Server and GitLab playbooks, restart the entire GitLab slice to re-populate Redis. You might expect existing GitLab sessions to be invalid and users to have to log in again.

• The debops.redis_server role will configure APT preferences on Debian Stretch to install Redis from the stretch-backports repository. The playbook run on existing installations will not upgrade the packages automatically, but you might expect it on normal system upgrade.

Changes related to packet forwarding in firewall and sysctl

• The debops.ifupdown role now uses debops.sysctl role directly as a dependency to generate forwarding configuration for each managed network interface that has it enabled. This might impact packet forwarding on existing systems; run the role with Ansible --diff --check options first to review the planned changes to the host.

• The debops.ferm role will no longer enable packet forwarding on all network interfaces. Existing /etc/sysctl.d/30-ferm.conf configuration file can be removed using the debops.debops_legacy role.

  The debops.ferm role will remove firewall rules that enabled forwarding between "external" and "internal" network interfaces, named forward_external_in, forward_external_out and forward_internal. They are redundant with the similar firewall rules generated by the debops.ifupdown role and their removal shouldn't impact connectivity, however you should check the modifications to the firewall just in case.

Redesigned DNSmasq support

• The debops.dnsmasq role has been redesigned from the ground up. The configuration is now merged from multiple sources (role defaults, Ansible inventory), role defines separate subdomains for each of the network interfaces, and automatically enables support for local Consul DNS service or LXC subdomain if they are detected on the host.

• Most of the dnsmasq__* default variables that defined the dnsmasq configuration have been removed. Their functionality is exposed either as parameters of network interface configuration, or can be easily changed via the main configuration pipeline. See the documentation of dnsmasq__configuration or dnsmasq__interfaces for more details. If you use DNSmasq on a host managed by DebOps, you will have to modify your Ansible inventory.

• The generated dnsmasq configuration has been split from a single 00_main.conf configuration file into multiple separate files stored in the /etc/dnsmasq.d/ directory. The old 00_main.conf configuration file will be automatically removed if found, to avoid issues with duplicated configuration options.

• The role provides an easy to use way to define DHCP clients with IP address reservation, as well as DNS resource records. See dnsmasq__dhcp_hosts, dnsmasq__dns_records documentation for examples and more details.

• The configuration of TCP Wrappers for the TFTP service has been removed from the debops.dnsmasq role, and is now done via the debops.tcpwrappers Ansible role and its dependent variables.

Inventory variable changes

• The debops.grub role was redesigned, most of the grub_* default variables have been removed and the new configuration method has been implemented. The role variables have been namespaced, the role now uses grub__* variable naming scheme. Check the role documentation for details about configuring GRUB via Ansible inventory.

• Variables related to dhcp_probe in the debops.dhcpd role have been replaced with the variables from the debops.dhcp_probe role. They are now namespaced and mostly with the same value types.

  The new debops.dhcp_probe role utilizes systemd templated instances, and might not work correctly on older Debian/Ubuntu releases.

• The variables related to packet forwarding in the debops.ferm role and related roles have been removed:

  • ferm__forward

  • ferm__forward_accept

  • ferm__external_interfaces

  • ferm__internal_interfaces

  • libvirtd__ferm__forward

  • lxc__ferm__forward

  The related Ansible local fact ansible_local.ferm.forward has also been removed.

  You can use the debops.ifupdown role to configure packet forwarding per network interface, in the firewall as well as via the kernel parameters.

• Host and domain management has been removed from the debops.bootstrap role. This functionality is now done via the debops.netbase role, included in the bootstrap playbook. Some of the old variables have their new equivalents:

  Old variable name	New variable name	Changed value
  bootstrap__hostname_domain_config_enabled	netbase__hostname_config_enabled	No
  bootstrap__hostname	netbase__hostname	No
  bootstrap__domain	netbase__domain	No
  bootstrap__etc_hosts	Removed	No
  bootstrap__hostname_v6_loopback	Removed	No

  Support for configuring IPv6 loopback address has been removed entirely. This was required when some of the DebOps roles relied on the ansible_fqdn value for task delegation between hosts. Since then, task delegation has been updated to use the inventory_hostname values and ensuring that the IPv6 loopback address resolves to a FQDN address of the host is no longer required.

• The netbase__*_hosts variables in the debops.netbase role have been redesigned to use YAML lists instead of dictionaries. See netbase__hosts for more details.

• The resources__group_name variable has been removed in favor of using all the groups the current hosts is in. This change has been reflected in the updated variable resources__group_templates. If you need to use a specific group update the resources__group_templates accordingly. Read the documentation about resources__templates for more details on templating with debops.resources.

Changes related to LXC containers

• The debops.lxc role will configure new LXC containers to attach to the lxcbr0 bridge by default. Existing LXC containers will not be modified. You can change the default bridge used on container creation using the lxc__configuration variables.

• The debops.lxc role has been updated to use the systemd lxc@.service instances to manage the containers instead of using the lxc-* commands directly. Existing LXC containers should not be affected, but it is recommended to switch them under the systemd control. To do that, you should disable the container autostart in the /var/lib/lxc/<container>/config configuration files:

  lxc.start.auto = 0
  

  This will make sure that the containers are not started by the lxc.service service on boot. Next, after stopping the running containers, enable and start the containers via the systemd instance:

  systemctl enable lxc@<container>.service
  systemctl start lxc@<container>.service
  

  This should ensure that the containers are properly shut down and started with the host system.

v0.8.0 (2018-08-06)

UNIX account and group configuration

• Configuration of UNIX system groups and accounts included in the admins UNIX group has been removed from the debops.auth role. This functionality is now done by the debops.system_groups role. The variable names and their values changed, see the debops.system_groups role documentation for details.

GitLab gitaly installation

• The debops.gitlab role will now build and install the gitaly service using unprivileged git UNIX account instead of root. To perform the update correctly, you might need to remove directories

  /usr/local/src/gitlab/gitlab.com/gitaly.git/
  /var/local/git/gitaly/
  

  Some files in these directories are owned by root and that can prevent the correct build of the Go binaries. You might also want to stop the gitlab-gitaly.service service and start it afterwards.

  The above steps shouldn't impact new GitLab installations.

UTF8 encoding in MariaDB

• The debops.mariadb_server and debops.mariadb roles will now use the utf8mb4 character encoding by default. This encoding is the real UTF-8 encoding and not the internal MySQL encoding. This change might impact existing MySQL databases; you can read an UTF-8 conversion guide to check if your database needs to be converted.

Inventory variable changes

• The console_preferred_editors list has been removed, configuration of the preferred vim editor is now done in the debops.apt_install role which also installs it.

• The console_custom_files variable has been removed along with the functionality in debops.console role. Use the debops.resources role variables to copy custom files instead. The role is also included in the common playbook, although a bit earlier, which shouldn't impact normal use cases.

• The management of the /etc/hosts file has been removed from the debops.console role and is now done via the debops.netbase role which has to be enabled through the Ansible inventory. The variables have been renamed:

  Old variable name	New variable name	Changed value
  console_hosts	netbase__hosts	No
  console_group_hosts	netbase__group_hosts	No
  console_host_hosts	netbase__host_hosts	No

• Configuration of the APT autoremove options has been moved from the debops.apt role to the debops.apt_mark role, because the latter role has more specific scope. The variable names as well as their default values have been changed to correctly reflect the meaning of the corresponding APT configuration options:

  Old variable name	New variable name	Changed value
  apt__autoremove_recommends	apt_mark__autoremove_recommends_important	Yes, to True
  apt__autoremove_suggests	apt_mark__autoremove_suggests_important	Yes, to True

  By default the APT packages installed via Recommends or Suggests dependencies will not be considered for autoremoval. If the user sets any package configuration via debops.apt_mark role, the autoremoval will be enabled automatically.

• The bootstrap__sudo and bootstrap__sudo_group variables have been removed from the debops.bootstrap role. The bootstrap.yml playbook now uses the debops.sudo role to configure sudo service on a host, use its variables instead to control the service in question.

• The bootstrap__admin_groups variable will now use list of UNIX groups with root access defined by the debops.system_groups via Ansible local facts.

• The contents of the sshd__allow_groups variable have been moved to the new sshd__default_allow_groups variable. The new variable also uses the debops.system_groups Ansible local facts as a data source.

• The bootstrap__raw and bootstrap__mandatory_packages variables have been removed. See the debops.python role documentation for their equivalents.

• The apt_install__python_packages variable has been removed from the debops.apt_install role. Use the debops.python Ansible role to install Python packages.

• The nodejs__upstream_version variable has been renamed to nodejs__node_upstream_release to better represent the contents, which is not a specific NodeJS version, but a specific major release.

• The gitlab_domain variable, previously used to set the FQDN of the GitLab installation, now only sets the domain part; it's value is also changed from a YAML list to a string.

  The gitlab__fqdn variable is now used to set the GitLab FQDN and uses the gitlab_domain value as the domain part.

v0.7.2 (2018-03-28)

No changes.

v0.7.1 (2018-03-28)

X.509 certificate changes

• The debops.pki role now generates the default X.509 certificate for the domain PKI realm with a wildcard entry for the host's FQDN (for example, *.host.example.org). This will be true by default on new hosts introduced to the cluster; if you want your old hosts to have the new X.509 certificates, you need to recreate the domain PKI realm by removing the /etc/pki/realms/domain/ directory on the remote hosts and re-running the debops.pki role against them.

  The change is done in the pki_default_realms variable, if you redefined it in the Ansible inventory, you might want to update your version to include the new SubjectAltName entry.

• The latest acme-tiny Python script uses ACMEv2 API by default, and the debops.pki role is now compatible with the upstream changes. The ACME certificates should work out of the box in new PKI realms, after the acme-tiny installation is updated.

  The existing PKI realms will stop correctly regenerating Let's Encrypt certificates, because their configuration is not updated automatically by the role. The presence of the acme/error.log file will prevent the acme-tiny script from requesting the certificates to not trip the Let's Encrypt rate limits.

  Easiest way to fix this is to remove the entire PKI realm (/etc/pki/realms/*/ directory) and re-run the debops.pki role against the host. The role will create a new PKI realm based on the previous configuration and ACME certificates should start working again. Services like nginx that have hooks in the /etc/pki/hooks/ directory should be restarted automatically, you might need to manually restart other services as needed.

  Alternatively, you can update the Let's Encrypt API URL in the realm's config/realm.conf file by replacing the line:

  config['acme_ca_api']='https://acme-v01.api.letsencrypt.org'
  

  with:

  config['acme_ca_api']='https://acme-v02.api.letsencrypt.org/directory'
  

  This should tell the pki-realm script to send requests for new certificates to the correct URL. You still need to run the debops.pki role against the host to install the updated pki-realm script and update the acme-tiny script.

Role changes

• The debops.debops role now uses the debops.ansible role to install Ansible instead of doing it by itself. The relevant code has been removed, see the debops.ansible role documentation for new variables.

• The debops-contrib.kernel_module role has been replaced by the debops.kmod role. All of the variable names have been changed, as well as their usage. See the documentation of the new role for more details.

• The debops.proc_hidepid role was modified to use a static GID 70 for the procadmins group to allow synchronization between host and LXC containers on that host. The role will apply changes in the /etc/fstab configuration file, but it will not change existing /proc mount options. You need to remount the filesystem manually, with a command:

  ansible all -b -m command -a 'mount -o remount /proc'
  

  The /proc filesystem mounted inside of LXC containers cannot be remounted this way, since it's most likely mounted by the host itself. You will need to check the LXC container configuration in the /var/lib/lxc/*/config files and update the mount point options to use the new static GID. Restart the LXC container afterwards to remount the /proc filesystem.

  You will also need to restart all services that rely on the procadmins group, for example snmpd, to activate the new GID.

• The debops.sysctl configuration has been redesigned. The role now uses YAML lists instead of YAML dictionaries as a base value of the sysctl__*_parameters default variables. The kernel parameter configuration format has also been changed to be easy to override via Ansible inventory. Role can now configure multiple files in /etc/sysctl.d/ directory. Refer to the role documentation for details.

Inventory variable changes

• The debops.netbox role has been updated, some variable names were changed:

  Old variable name	New variable name	Changed value
  netbox__config_netbox_username	netbox__config_napalm_username	No
  netbox__config_netbox_password	netbox__config_napalm_password	No

• The variables that specify files to ignore in the new debops.etckeeper role have been renamed from their old versions in debops-contrib.etckeeper role, and their value format changed as well. See the documentation of the new role for details.

v0.7.0 (2018-02-11)

This is mostly a maintenance release, dedicated to reorganization of the DebOps git repository and expanding documentation.

Role changes

• The debops.nodejs role now installs NPM using a script in upstream git repository. This might cause issues with already installed NPM package, because of that it will be automatically removed by the role if found. You should verify that the role behaves correctly on existing systems before applying it in production.

• The debops.gunicorn role has rewritten configuration model based on systemd instanced units. The existing configuration shouldn't interfere, however you might need to update the Ansible inventory configuration variables to the new syntax.

Inventory variable changes

• The localization configuration previously located in the debops.console role is now located in the debops.locales role. List of default variables that were affected:

  Old variable name	New variable name	Changed value
  console_locales	locales__default_list	No
  console_locales_default	locales__system_lang	No

  There are also new localization variables for all hosts, group of hosts, specific hosts and dependent roles.

• The /etc/issue and /etc/motd configuration has been removed from the debops.console role and is now done by the debops.machine role. List of default variables that were affected:

  Old variable name	New variable name	Changed value
  console_issue	machine__organization	No
  console_motd	machine__motd	No

  The support for dynamic MOTD has been implemented by the debops.machine role, you might want to use that instead of the static MOTD file.

• Configuration of the /proc hidepid= option has been removed from the debops.console and is now available in the new debops.proc_hidepid Ansible role. List of default variables that were affected:

  Old variable name	New variable name	Changed value
  console_proc_hidepid	proc_hidepid__enabled	No
  console_proc_hidepid_level	proc_hidepid__level	No
  console_proc_hidepid_group	proc_hidepid__group	No

  The logic to enable/disable the hidepid= configuration has been moved to the proc_hidepid__enabled variable to be more accessible. The role creates its own set of Ansible local facts with new variable names, you might need to update configuration of the roles that relied on them.

• Configuration of the sysnews package has been removed from the debops.console role, it's now available in the debops.sysnews Ansible role. There were extensive changes in the variable names and parameters, read the documentation of the new role for details.

v0.6.0 (2017-10-21)

This is an initial release based off of the previous DebOps roles, playbooks and tools located in separate git repositories. There should be no changes needed between the old and the new infrastructure and inventory.