Ansible Role: Dnsmasq for MacOS

Role is used to automate installation and setup of dnsmasq. Dnsmasq provides network infrastructure for small networks: DNS, DHCP, router advertisement and network boot.

By default, role configures Dnsmasq to serve *.docker and *.mac domains as localhost. This allows you to use wildcard domains, like your.subdomain.project.docker for every of your project.

→ Purpose

Developers will be familiar with the process of updating your /etc/hosts file to direct traffic for yourproject.docker to 127.0.0.1. Most will also be familiar with the problems of this approach:

• it requires a configuration change every time you add or remove a project; and
• it requires administration access to make the change.

For *nix and MacOS users there is a solution – Dnsmasq, which replaces the need for you, to edit the hosts file for each project you work with. Dnsmasq works good together with Træfik and Docker.

There is a known issue with Docker for Mac – ".localhost DNS doesn’t resolve in browsers other than Chrome". Users who are working on Windows and using WSL or without it, will also have problems to get wildcard domains like my.virtual.host.docker working. For them, there is other thread and solutions described on superuser.com.

If you like/use this role, please consider starring it. Thanks!

📑 Requirements

• Up-to-date version of ansible. During maintenance/development, we stick to ansible versions and will use new features if they are available (and update meta/main.yml for the minimum version).
• Compatible OS. See compatibility table.
• jmespath library needs to be installed on the host running the playbook (needed for the json_query filter).
• Role has dependencies on third-party roles on different operating systems. See requirements.yml and dependencies section.

🔧 Role Variables

Available variables are listed below, along with example values (see defaults/main.yml). Additional variables are stored in vars/main.yml.

→ Structure

Add domain names that will be mapped to ip addresses. Defaults should be fine, if you are using our wayofdev/mac-provisioner playbook:

dnsmasq_hosts:
  # Mapping some top level domains to localhost
  - {domain: 'docker', ip: '127.0.0.1'}
  - {domain: 'mac', ip: '127.0.0.1'}

📗 Example Playbook

---
- hosts: all

  # is needed when running over SSH
  environment:
    - PATH: "/usr/local/bin:/usr/local/sbin:/opt/homebrew/bin:{{ ansible_env.PATH }}"

  vars:
    dnsmasq_hosts:
      - {domain: 'docker', ip: '127.0.0.1'}
      - {domain: 'mac', ip: '127.0.0.1'}

  roles:
    - wayofdev.homebrew
    - wayofdev.dnsmasq

⚙️ Development

To install dependencies and start development you can check contents of our Makefile

Install poetry using poetry-bin and all dev python dependencies:

$ make install

Install only python dependencies, assuming that you already have poetry:

$ make install-deps

Install all git hooks:

$ make hooks

Lint all role files:

$ make lint

🧪 Testing

You can check Makefile to get full list of commands for remote and local testing. For local testing you can use these comands to test whole role or separate tasks:

→ on localhost

⚠️ Notice: By defaut all tests are running against your local machine!

# run molecule tests on localhost
$ poetry run molecule test --scenario-name defaults-restored-on-localhost -- -vvv

# or with make command
$ make m-local

# choose which tags will be included
$ export TASK_TAGS="dnsmasq-install,dnsmasq-configure"; make m-local

→ over SSH

# run molecule scenarios against remote machines over SSH
# this will need VM setup and configuration
$ poetry run molecule test --scenario-name defaults-restored-over-ssh -- -vvv

$ make m-remote

# tags also can be passed
$ export TASK_TAGS="dnsmasq-install,dnsmasq-configure"
$ make m-remote

📦 Dependencies

Installation handled by Makefile and requirements are defined in requirements.yml

• wayofdev.homebrew - soft dependency, required if Homebrew isn't installed yet
• ansible.community.general

🧩 Compatibility

This role has been tested on these systems:

system / container	tag
macos	monterey
macos	big-sur

🤝 License

🙆🏼‍♂️ Author Information

This role was created in 2022 by lotyp / wayofdev.

🧱 Credits and Resources

What I've found on internet:

• robertdebock/ansible-role-dnsmasq ansible role to manage dnsmasq on Alpine, Debian, Fedora, Ubuntu...
• Also Debian/Ubuntu users can take a look at Debops's Dnsmasq role.
• An Ansible role for managing Dnsmasq on RHEL/CentOS 7 of Fedora. bertvv/ansible-dnsmasq

🫡 Contributors