buildhosts/README.md

2.1 KiB

BuildHosts

Download and use custom hosts sources to build /etc/hosts

Commands

  • buildhosts build: generate /etc/hosts using /etc/hosts.core and the configured sources
  • buildhosts revert: remove lists imported from hosts list sources and restore /etc/hosts
  • buildhosts help: display the help

Configure Hosts Sources

  1. Running buildhosts build for the first time will move /etc/hosts to /etc/hosts.core and create /etc/hosts.sources with a set of default hosts sources that focus on ad-blocking, and these will be downloaded before a new /etc/hosts is then created using /etc/hosts.core and the contents of the hosts sources.
  2. Once this is finished, you can add/edit/delete or comment (lines starting with #) hosts sources in /etc/hosts.sources, and running buildhosts build again will re-create /etc/hosts using your updated sources.

Remove Hosts Sources

  1. To disable the configured hosts lists and restore your original configuration, run buildhosts revert and /etc/hosts.core will be moved back to /etc/hosts (/etc/hosts.sources will need to be manually deleted).

Environment Variables

These variables can be configured before running buildhosts to run with custom locations

  • HOSTS_DIR: Directory containing the hosts file (default: /etc/)
  • HOSTS_SYSTEM: The system hosts file (default: $HOSTS_DIR/hosts)
  • HOSTS_CORE: The file containing the custom hosts configuration (default: ${HOSTS_SYSTEM}.core)
  • HOSTS_SOURCES: The file containing a list of hosts sources to download (default: ${HOSTS_SYSTEM}.sources)
  • HOSTS_WHITELIST: The file containing a list of domains to skip when parsing $HOSTS_SOURCES (default: ${HOSTS_SYSTEM}.whitelist)

Extra

  • The p2p-to-hosts script included in this repo can be used to convert blocklists in p2p format to hosts format (usable with this package).

Credits

Written by Kevin MacMartin:

License

Released under the MIT license.