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:
- Install an SSH authorized key.
- Set admin user password.
- Configure DNS servers with DNSSEC and “DNS over TLS” support.
- Configure NTP servers with NTS support.
- Set Grub timeout.
- Set Grub password.
- Configure DNF proxy, weak dependencies, parallel downloads.
- Enable DNF auto-updates (With auto-restart).
- Set up NFS and CIFS/SMB shares.
- Set up
rootuser mail redirection with SMTP relay on an external server. - Install custom CA certificates.
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:
- Works with SELinux enforced.
- SSH hardening:
- Hardened SSHd configuration.
- Restricted SSH accesses using firewall.
- Fail2ban SSH jail
- Optional Linux kernel hardening, including:
- Protection against common memory issues like use-after-free.
- Various Kernel vulnerabilities prevention like DMA attacks.
- Network hardening against various attacks (Man In The Middle, Denial of service, …).
- Deactivation of uncommon or vulnerable kernel modules.
- Kernel sensitive data protection or restricted access (Coredump, dmesg, …)
- Optional Linux kernel lockdown mode.
- Optional CPU vulnerabilities mitigation configuration.
- Optional installation of the Netdata agent (As standalone cloud connected node, or as thin child node streaming to a parent).
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:
- NFS and SMB shares are added to
/etc/fstabbut not mounted: they are mounted at the next boot, before modules loading is disabled. cachefilesdis enabled but not started: it starts at the next boot.- Netdata sensors detection (
sensors-detect) does not run.
Other steps that need a module not already loaded fail, such as some firewall changes. To run all steps:
- Set
common_os_hardening_disable_kernel_module_loadingtofalse, run the role, then reboot. - 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.