ansible_home

A collection of Ansible roles for home free software self-hosting.

View on GitHub

Common Ansible Role

Description

This role initializes a new host by performing some common configuration tasks.

This role is compatible with both dnf and rpm-ostree based Fedora. This role is suitable to use for servers, but also for workstations or laptops.

Features

Configure:

Security:

This role also aims to improve the system security by providing many security-related optional and default features.

The goal is mainly to reduce the attack surface and protect against common security vulnerabilities classes.

Non-exhaustive list of changes:

The most intrusive security options are optional and can be disabled by re-running the role and changing options.

Hardening options in this role are tweaked for Fedora. Options that are not relevant on Fedora or already enabled on it are not included here. This role limits to security options that can be achievable using configuration files and Fedora repositories packages.

Variables

Optional

Name Default Value Description
common_admin_password   If specified, set this password for the current remote user. Must be a hashed password (generate with mkpasswd --method=yescrypt).
common_allow_bluetooth false If true, allow Bluetooth. Only apply with common_os_hardening set to true.
common_allow_ntfs false If true, allow the in-kernel NTFS filesystem (ntfs3). Only apply with common_os_hardening set to true. Enable this if the host needs to mount NTFS-formatted external drives (for instance Kodi media libraries shared with Windows).
common_allow_thunderbolt false If false, disable Thunderbolt and Firewire.
common_allow_usb true If false, disable USB.
common_ca_certificates   If specified, CA certificates to install in the system CA trust store. Must be a list of local path to PEM or DER formatted certificates. Certificates the role installed (files with the ansible-common- prefix) and no longer listed, or all of them when unset, are removed from the trust store. Copies a previous role version wrote under the original file name are removed only when identical to the listed file.
common_cpu_vulnerabilities_mitigation auto Configure kernel CPU vulnerabilities mitigations. Possible values are auto to enable all mitigations (Default kernel behavior), off to disable all mitigations (Best performance, weakest security), auto,nosmt to enable all mitigations and disable SMT if required (Best security, lowest performance).
common_dnf_automatic_on_shutdown false If true, trigger DNF automatic updates on system shutdown instead of using timer. Ignored on Ostree based OS.
common_dnf_automatic_restart true If true, restart the host if required when performing DNF automatic updates. Disabled if common_dnf_automatic_on_shutdown is true. Ignored on Ostree based OS.
common_dnf_automatic_upgrade_type default The type of update installed by DNF automatic. Possible values are default (all available updates) or security (only security updates; may improve stability). Ignored on Ostree-based OS.
common_dnf_fastestmirror false If true, use a mirror selection metric to find the fastest available mirror. Many repositories already direct clients to fast mirrors dynamically; enabling fastestmirror can override that behavior. Ignored on Ostree-based OS.
common_dnf_install_weak_deps false If "true", configure DNF to install weak dependencies. Ignored on Ostree based OS.
common_dnf_keepcache false If "true", configure DNF to keep the package cache. Ignored on Ostree based OS.
common_dnf_nodocs true If true, disable documentation installation.
common_dnf_proxy   URL of a proxy server to connect through The expected format of this option is <scheme>://<ip-or-hostname>[:port]. If you configured another host with the squid role, you may set this value to http://<squid-host-ip-or-hostname>:<squid-port>. Ignored on Ostree based OS.
common_dnf_proxy_auth_method   If the proxy requires authentication, the authentication method to use. Ignored on Ostree based OS.
common_dnf_proxy_password   If the proxy requires authentication, the password to use. The DNF drop-in is world-readable (0644) so that DNF works for non-root users, so the password is readable by every local user. Ignored on Ostree based OS.
common_dnf_proxy_username   If the proxy requires authentication, the username to use. Ignored on Ostree based OS.
common_dnf_sslcacert   If specified, file containing the certificate authorities to verify SSL certificates. If not specified, use system defaults. Can be used to specify proxy certificate when used with common_dnf_proxy. Ignored on Ostree based OS.
common_dns_over_tls opportunistic Enable DNS over TLS. "yes" is recommended if DNS server support DNS over TLS because opportunistic mode is more vulnerable. "no" to enforce classical unencrypted DNS.
common_dns_servers   Space-separated list of DNS servers to use, if not set will use the default value generally provided by the DHCP server. If common_dns_over_tls is set to "yes", it is recommended to servers values to address#server_name to allow certificate validation. When unset, the setting is removed from the role drop-in.
common_dns_servers_fallback "1.1.1.1 9.9.9.9 1.0.0.1 149.112.112.112 2606:4700:4700::1111 2620:fe::fe 2606:4700:4700::1001 2620:fe::9" Space-separated list of fallback DNS servers to use. The default use Cloudflare and Quad9 DNS servers (Google is replaced for privacy reason).
common_dnssec   If "yes", enforce DNSSEC validation locally, else use default configuration. The DNS server must support DNSSEC. When unset, the setting is removed from the role drop-in.
common_domain   Domain/FQDN of the current machine. When unset, the packaged ::1 line of /etc/hosts is restored; the rest of the file, .rpmnew and .rpmsave are left to the admin.
common_fail2ban_action %(action_mw)s if common_mail_smtp_host is set, else %(action_)s Fail2ban default action. By default, ban user and send mail to root when mail is configured.
common_fs_cache false If true, configure cachefilesd to cache network file system. To use it with NFS or SMB mounts, set this value to true and add fsc to mount options. If false, cachefilesd is removed.
common_grub_auto_hide false If true configure Grub to auto-hide. On rpm-ostree hosts, the menu is hidden for common_grub_hidden_timeout seconds instead.
common_grub_cmdline_linux_default   Space-separated list of extra Linux kernel options passed on boot using GRUB_CMDLINE_LINUX_DEFAULT, or rpm-ostree kargs on rpm-ostree hosts.
common_grub_hidden_timeout 0 Grub hidden timeout to set.
common_grub_password   If specified, ensure Grub password is set to this value. It protects editing boot entries and the Grub console; entries still boot without it, so unattended reboots keep working.
common_grub_save_default false If true configure Grub to use the last used entry as default. Ignored on rpm-ostree hosts, where it would keep booting an older deployment after an update. If false, GRUB_SAVEDEFAULT is removed and GRUB_DEFAULT is left as it is.
common_grub_timeout 1 Grub timeout to set. On rpm-ostree hosts, where grub2-mkconfig is not supported and /etc/default/grub is not used, the menu settings are written to a block in /boot/grub2/custom.cfg, which Grub reads last: they also replace a request to show the menu once.
common_guest_incus false If true Install Incus guest agent.
common_guest_qemu false If true Install Qemu guest agent.
common_hostname   If specified, set hostname.
common_journal_disk_max_size   If specified, set systemd journal disk max size (SystemMaxUse). When both journal variables are unset, the role drop-in is removed.
common_journal_memory_max_size   If specified, set systemd journal memory max size (RuntimeMaxUse).
common_kernel_lockdown integrity Kernel lockdown mode to enable. Possible values are integrity (protect kernel from modification — blocks unsigned module loading, /dev/mem writes, kexec_load, BPF that writes kernel state, etc.), confidentiality (integrity plus anti-extraction of kernel memory — also blocks hibernation, many eBPF tracing paths used by Netdata ebpf.plugin, kernel debugging via perf/bpftrace, /proc/kcore reads and some VFIO/PCIe-passthrough scenarios), or an empty string to disable. Set to "" on hosts that load unsigned out-of-tree modules (e.g. unsigned akmods without MOK enrollment).
common_login_password_min_length 12 Minimal password size.
common_mail_smtp_host   SMTP server host. When unset, the Postfix relay configuration written by the role (relay host, SASL, TLS, root alias, service drop-in) is reverted to the packaged one, only if the role’s service drop-in exists and main.cf holds no other active relayhost line (an empty one counts, so a Postfix set up by the mail role is left alone). The SASL password files are deleted only when main.cf references them.
common_mail_smtp_inet_interfaces 127.0.0.1 Interface from where accept SMTP requests. By default, localhost only. Only if common_mail_smtp_host is specified.
common_mail_smtp_password   Password of the common_mail_smtp_user user on the SMTP server. Only if common_mail_smtp_host is specified.
common_mail_smtp_port 465 SMTP server port to use, can be: 25 (SMTP), 465 (SMTPS), 587 (SMTP-Submission). Only if common_mail_smtp_host is specified.
common_mail_smtp_user   User to authenticate on the SMTP server, if specified enable SMTP authentication. Only if common_mail_smtp_host is specified. When unset, the SASL configuration is removed, and the password files too when main.cf references them.
common_mail_smtp_tls TLS Security mode to use. Possible values are TLS (For SMTPS) or STARTTLS (for SMTP/SMTP-Submission).
common_mail_smtp_send_to   If specified, redirect all root mails to the specified email address. When unset, the packaged root alias is restored.
common_netdata_claim_rooms   If specified, claim the Netdata node in the specified room. common_netdata_claim_token is required. Value is the room UUID in Netdata Cloud.
common_netdata_claim_token   If specified, claim Netdata node in the cloud using the specified token. Value is the token from the Netdata cloud. common_netdata_claim_rooms is required.
common_netdata_cloud_only false If true, Netdata dashboard is only reachable from Netdata cloud. common_netdata_claim_token is required.
common_netdata_enable false If true, install the Netdata agent. If false, uninstall Netdata with everything it stored, even when a person installed it from its RPM packages: its packages, DNF repository and cached metadata, signing keys, netdata user and group, configuration (/etc/netdata), metrics and node identity (/var/lib/netdata, /var/cache/netdata), logs (/var/log/netdata and its journal namespace) and the installer leftovers. lm_sensors goes too when the role’s drop-in for it exists (the role installs both for Netdata). A static install in /opt/netdata is not removed. This runs before the OS upgrade check, so a host whose upgrade only Netdata’s repository blocked upgrades in the same run. A node claimed to Netdata Cloud stays listed there as offline: remove it from the Cloud. Other roles also remove their Netdata collectors and accesses.
common_netdata_ephemeral_node false If true, node is configured as “ephemeral” instead of “permanent” (Should be set to true to any server that is stopped frequently).
common_netdata_stream_api_key   If specified, configure Netdata stream using the specified API Key. common_netdata_stream_destination is required.
common_netdata_stream_destination   If specified, configure Netdata stream to the specified parent destination. If configured, and common_netdata_claim_token is not configured, configure the agent as a thin agent that only stream to the parent. common_netdata_stream_api_key is required.
common_nfs_mount   If specified, mount specified NFS shares. Must be a list of mapping (one per share to mount) with keys: path (mount point path), src (share to mount), opts (optional, mount options, see fstab(5)), owner (optional, user owning the mount), group (optional, group owning the mount), mode (optional, permission mode) , state (optional, present if require to only add it to /etc/fstab without applying it now).
common_ntp_server   If specified, configure Chrony to use the specified NTP server. Other pool and server sources are removed. NTP servers announced by DHCP are ignored while it is set. When unset, the packaged Fedora pool and DHCP sources are restored.
common_nts false If true, configure Chrony to enable NTS (Network Time Security). The server specified by common_ntp_server must support NTS. Only NTS authenticated sources are then selected (authselectmode require), with no unauthenticated fallback: the host stays unsynchronized if the NTS key exchange fails (port 4460/tcp must be reachable). Certificate time checks are skipped for the first sync (nocerttimecheck 1), so a host with a wrong clock at boot can still synchronize.
common_os_hardening true If true, apply the OS hardening baseline. Setting it back to false removes it; some kernel settings (such as kernel.kexec_load_disabled) keep their hardened value until the next reboot. With it, the kernel logs that some drivers cannot create their debugfs entries (debugfs=off): the price of keeping kernel internals unreadable.
common_os_hardening_disable_kernel_module_loading false If true, disable kernel modules loading at each boot, once the boot services have loaded their modules (disable-kernel-modules-loading.service). Applies from the next reboot. Only apply with common_os_hardening set to true. Any later module load fails until reboot (hot-plugged devices, VPN, containers networking, new firewall features). See “Kernel modules loading is disabled” in known issues.
common_os_hardening_disable_user_namespaces false If true, disable user namespaces. Only apply with common_os_hardening set to true. User namespaces is required for containers (Docker, Podman, …) and PrivateUsers= Systemd sandboxing feature, this option must be disabled to use them.
common_os_hardening_interactive_timeout 600 Timeout for interactive sessions before logout. Only apply with common_os_hardening set to true.
common_os_hardening_kernel_ia32_emulation false If false, Reduce attack surface by disabling x86 32-bit emulation on x86-64. Only apply with common_os_hardening set to true.
common_os_hardening_localpkg_gpgcheck true If true, requires that local packages are signed to be installed. This will interfere with akmods and should be disabled if using it.
common_os_hardening_multicast_dns true when the play has the kodi, mpd or musicplayer role, else false If false, turn off multicast name resolution, which any host on the link can spoof: LLMNR and mDNS in systemd-resolved, the Avahi mDNS responder (a drop-in keeps its units from starting, so their enablement is unchanged) and the mdns service in the public firewalld zone. Multimedia hosts keep it for Zeroconf, AirPlay and device discovery. Only apply with common_os_hardening set to true; otherwise the packaged settings are restored.
common_os_target_release   If specified, the target OS release for upgrade. Else, default to the latest available Fedora version. If the current OS version is equal to common_os_target_release - 1, the OS will be upgraded to the common_os_target_release automatically, unless common_os_upgrade_check_repositories finds a blocker. Currently, this feature is not available for ostree Fedora variants.
common_os_upgrade_check_repositories true If true, before upgrading the OS, check that every enabled repository publishes metadata for the target release and that the upgrade resolves (dnf system-upgrade download --assumeno). If not, skip the upgrade without failing and show a warning listing the repositories and packages that block it (third-party repositories often lag behind Fedora releases). If false, the upgrade runs and fails on such blockers.
common_random_mac false If true, configure NetworkManager to use random MAC addresses. See common_random_mac_wifi and common_random_mac_ethernet to choose per-interface randomization modes.
common_random_mac_wifi random Random MAC address mode when using WIFI, random to generate a new random MAC address on each connection, stable to generate a random MAC address per network (per NetworkManager connection profile), kept across reboots. When using random, it is still possible to configure a specific network to stable using nmcli c modify UUID 802-11-wireless.cloned-mac-address stable (With UUID the value from with nmcli c \| grep wifi).
common_random_mac_ethernet stable Random MAC address mode when using Ethernet, random to generate a new random MAC address on each connection, stable to generate a random MAC address per network (per NetworkManager connection profile), kept across reboots, or permanent to use the real interface MAC address.
common_smb_mount   If specified, mount specified CIFS/SMB shares. The value format is identical to common_nfs_mount.
common_ssh_authorized_key   If specified, add the specified SSH public key to ~/.ssh/authorized_keys. If common_ssh_hardening is set to true, this also disable password authentication. (A key can be generated using ssh-keygen -t ed25519)
common_ssh_hardening true If true, set a hardened configuration on the SSH server. It accepts only the ML-KEM, NTRU Prime and Curve25519 key exchanges, the ChaCha20-Poly1305 and AES-GCM ciphers and encrypt-then-MAC SHA-2 or UMAC MACs: clients limited to NIST curves (such as clients in FIPS mode) or older algorithms cannot connect.
common_trusted_firewalld_source   If specified, configure Firewalld to authorize SSH access only from the specified sources list in CIDR notation (["192.168.1.10/32", "192.168.1.0/24", "2001:db8:1234:5678::/64"], …). SSH is removed from both the public zone and the firewalld default zone (e.g. FedoraServer, FedoraWorkstation). Sources removed from the list are removed from the admin zone. When unset, the admin zone is removed and SSH is allowed again in the public and default zones.

Example Playbook

Example of remotely configuring a server:

---
- hosts: all
  become: true
  force_handlers: true  # See known issues
  collections:
    - jgoutin.home
  roles:
    - common
  vars:
    common_ssh_authorized_key: ssh-ed25519 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
    common_ntp_server: 192.168.1.1
    common_trusted_firewalld_source: 192.168.1.10/32

Example of locally configuring a laptop:

---
- hosts: localhost
  become: true
  force_handlers: true  # See known issues
  collections:
    - jgoutin.home
  roles:
    - common
  vars:
    # Ensure Laptop devices are allowed
    common_allow_bluetooth: true
    common_allow_thunderbolt: true
    # Use random MAC address
    common_random_mac: true

Known issues

Ansible dependencies are not cleaned on failure

Some modules and sub-roles of this role require installing some packages on the host to work. Since these packages are not required once the Ansible play is done, this role provides handlers to clean up these packages.

In case of failure during the Ansible play, handlers are not applied and packages are not cleaned up.

To avoid this issue and ensure the cleanup is performed, add force_handlers: true in the playbook.

Failure with common_admin_password variable

When using the common_admin_password variable, the playbook may fail on the first step that follow Ensure current user password is set with the message Incorrect sudo password.

In this case, simply re-run the playbook and enter the new password when asked by Ansible (BECOME password).

If the failure is an issue in a complex playbook, do not use this variable to set the password.

Kernel modules loading is disabled

With common_os_hardening_disable_kernel_module_loading set to true, the disable-kernel-modules-loading.service unit sets kernel.modules_disabled=1 late in each boot. This setting cannot be reverted until the next reboot, so the role checks it at start. When it is set, the role displays a warning and skips the steps that may load a new kernel module:

Other steps that need a module not already loaded fail, such as some firewall changes. To run all steps:

  1. Set common_os_hardening_disable_kernel_module_loading to false, run the role, then reboot.
  2. Set it back to true, run the role, then reboot.

Setting the option to false removes the unit; modules loading stays disabled until the next reboot.