sergey/hosts
1
0
Fork 0
mirror of https://github.com/StevenBlack/hosts.git synced 2026-07-01 02:36:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Format readme_template.md to wrap at 80-columns.

Browse Source
This commit is contained in:
Steven Black
2016-12-18 23:43:52 -05:00
parent 85babd9720
commit 745dc5882c
1 changed files with 78 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

129
readme_template.md
View File

@@ -1,24 +1,29 @@
#Unified hosts file @EXTENSIONS_HEADER@
This repository consolidates several reputable `hosts` files, and merges them into a unified hosts file
with duplicates removed. This repo provides several hosts files tailored to you need to block.
This repository consolidates several reputable `hosts` files, and merges them
into a unified hosts file with duplicates removed. This repo provides several
hosts files tailored to you need to block.
* Last updated: **@GEN_DATE@**.
* Here's the [raw hosts file @EXTENSIONS_HEADER@](https://raw.githubusercontent.com/StevenBlack/hosts/master/@SUBFOLDER@hosts) containing @NUM_ENTRIES@ entries.
### List of all hosts file variants
The **Non Github mirror** is the link to use for some hosts file managers like [Hostsman for Windows](http://www.abelhadigital.com/hostsman) that don't work with Github download links.
The **Non Github mirror** is the link to use for some hosts file managers like
[Hostsman for Windows](http://www.abelhadigital.com/hostsman) that don't work
with Github download links.
Host file recipe | Readme | Raw hosts | hosts (.zip) | Unique domains | Non Github mirror
---------------- |:------:|:---------:|:------------:|:--------------:|:-------------:
@TOCROWS@
**Expectation**: These unified hosts files should serve all devices, regardless of OS.
**Expectation**: These unified hosts files should serve all devices, regardless
of OS.
## Sources of hosts data unified in this variant
Updated `hosts` files from the following locations are always unified and included:
Updated `hosts` files from the following locations are always unified and
included:
Host file source | Description | Home page | Raw hosts | Update frequency
-----------------|-------------|:---------:|:---------:|:-------:
@@ -26,14 +31,17 @@ Host file source | Description | Home page | Raw hosts | Update frequency
## Extensions
The unified hosts file is extensible. You manage extensions by curating the `extensions/` folder tree. See the `social`, `gambling`, and `porn` extension folders.
The unified hosts file is extensible. You manage extensions by curating the
`extensions/` folder tree. See the `social`, `gambling`, and `porn` extension
folders.
## Generate your own unified hosts file
The `updateHostsFile.py` script, which is python 2.7 and Python 3-compatible, will generate a unified hosts file
based on the sources in the local `data/` subfolder. The script will prompt you Whether it should fetch updated
versions (from locations defined by the update.info text file in each source's folder), otherwise it will use the
`hosts` file that's already there.
The `updateHostsFile.py` script, which is python 2.7 and Python 3-compatible,
will generate a unified hosts file based on the sources in the local `data/`
subfolder. The script will prompt you Whether it should fetch updated
versions (from locations defined by the `update.json` text file in each
source's folder), otherwise it will use the `hosts` file that's already there.
### Usage
@@ -52,74 +60,92 @@ versions (from locations defined by the update.info text file in each source's f
`--auto`, or `-a`: run the script without prompting. When `--auto` is invoked,
* Hosts data sources, including extensions, are updated.
* No extensions are included by default. Use the `--extensions` or `-e` flag to include any you want.
* Your active hosts file is *not* replaced unless you include the `--replace` flag.
* No extensions are included by default. Use the `--extensions` or `-e` flag
to include any you want.
* Your active hosts file is *not* replaced unless you include the `--replace`
flag.
`--backup`, or `-b`: Make a backup of existing hosts file(s) as you generate over them.
`--backup`, or `-b`: Make a backup of existing hosts file(s) as you generate
over them.
`--extensions <ext1> <ext2> <ext3>`, or `-e <ext1> <ext2> <ext3>`: the names of subfolders below the `extensions` folder
containing additional category-specific hosts files to include in the amalgamation. Example: `--extensions porn` or
`-e social porn`.
`--extensions <ext1> <ext2> <ext3>`, or `-e <ext1> <ext2> <ext3>`: the names
of subfolders below the `extensions` folder containing additional
category-specific hosts files to include in the amalgamation. Example:
`--extensions porn` or `-e social porn`.
`--flush-dns-cache`, or `-f`: skip the prompt for flushing the DNS cache. Only active when `--replace` is also active.
`--flush-dns-cache`, or `-f`: skip the prompt for flushing the DNS cache.
Only active when `--replace` is also active.
`--ip nnn.nnn.nnn.nnn`, or `-i nnn.nnn.nnn.nnn`: the IP address to use as the target. Default is `0.0.0.0`.
`--ip nnn.nnn.nnn.nnn`, or `-i nnn.nnn.nnn.nnn`: the IP address to use as the
target. Default is `0.0.0.0`.
`--noupdate`, or `-n`: skip fetching updates from hosts data sources.
`--output <subfolder>`, or `-o <subfolder>`: place the generated source file in a subfolder. If the subfolder does not
exist, it will be created.
`--output <subfolder>`, or `-o <subfolder>`: place the generated source file
in a subfolder. If the subfolder does not exist, it will be created.
`--replace`, or `-r`: trigger replacing your active hosts
`--skipstatichosts`, or `-s`: `false` (default) or `true`, omit the standard section, at the top containing lines like `127.0.0.1 localhost`. This is useful for configuring proximate DNS services on the local network.
`--skipstatichosts`, or `-s`: `false` (default) or `true`, omit the standard
`--section, at the top containing lines like `127.0.0.1 localhost`. This is
`--useful for configuring proximate DNS services on the local network.
`--zip`, or `-z`: `false` (default) or `true`, additionally create a zip archive of the hosts file named `hosts.zip`.
`--zip`, or `-z`: `false` (default) or `true`, additionally create a zip
`--archive of the hosts file named `hosts.zip`.
## How do I control which sources are unified?
Add one or more *additional* sources, each in a subfolder of the `data/` folder, and specify the `url` key in its `update.json` file.
Add one or more *additional* sources, each in a subfolder of the `data/`
folder, and specify the `url` key in its `update.json` file.
Add one or more *optional* extensions, which originate from subfolders of the `extensions/` folder. Again the url in
`update.info` controls where this extension finds its updates.
Add one or more *optional* extensions, which originate from subfolders of the
`extensions/` folder. Again the url in `update.json` controls where this
extension finds its updates.
Create an *optional* `blacklist` file. The contents of this file (containing a listing of additional domains in
`hosts` file format) are appended to the unified hosts file during the update process. A sample `blacklist` is
Create an *optional* `blacklist` file. The contents of this file (containing a
listing of additional domains in `hosts` file format) are appended to the
unified hosts file during the update process. A sample `blacklist` is
included, and may be modified as you desire.
* NOTE: The `blacklist` is not tracked by git, so any changes you make won't be overridden when you `git pull`
this repo from `origin` in the future.
* NOTE: The `blacklist` is not tracked by git, so any changes you make won't
be overridden when you `git pull` this repo from `origin` in the future.
### How do I include my own custom domain mappings?
If you have custom hosts records, place them in file `myhosts`. The contents of this file are prepended to the
unified hosts file during the update process.
If you have custom hosts records, place them in file `myhosts`. The contents
of this file are prepended to the unified hosts file during the update
process.
The `myhosts` file is not tracked by git, so any changes you make won't be overridden when you `git pull` this repo from `origin` in the future.
The `myhosts` file is not tracked by git, so any changes you make won't be
overridden when you `git pull` this repo from `origin` in the future.
### How do I prevent domains from being included?
The domains you list in the `whitelist` file are excluded from the final hosts file.
The domains you list in the `whitelist` file are excluded from the final hosts
file.
The `whitelist` uses partial matching. Therefore if you whitelist `google-analytics.com`, that domain and all its
subdomains won't be merged into the final hosts file.
The `whitelist` uses partial matching. Therefore if you whitelist `google-
analytics.com`, that domain and all its subdomains won't be merged into the
final hosts file.
The `whitelist` is not tracked by git, so any changes you make won't be overridden when you `git pull` this repo
from `origin` in the future.
The `whitelist` is not tracked by git, so any changes you make won't be
overridden when you `git pull` this repo from `origin` in the future.
## What is a hosts file?
A hosts file, named `hosts` (with no file extension), is a plain-text file used by all operating
systems to map hostnames to IP addresses.
A hosts file, named `hosts` (with no file extension), is a plain-text file
used by all operating systems to map hostnames to IP addresses.
In most operating systems, the `hosts` file is preferential to `DNS`. Therefore if a domain name is
resolved by the `hosts` file, the request never leaves your computer.
In most operating systems, the `hosts` file is preferential to `DNS`.
Therefore if a domain name is resolved by the `hosts` file, the request never
leaves your computer.
Having a smart `hosts` file goes a long way towards blocking malware, adware, and other irritants.
Having a smart `hosts` file goes a long way towards blocking malware, adware,
and other irritants.
For example, to nullify requests to some doubleclick.net servers, adding these lines to your hosts
file will do it:
For example, to nullify requests to some doubleclick.net servers, adding these
lines to your hosts file will do it:
# block doubleClick's servers
0.0.0.0 ad.ae.doubleclick.net
@@ -229,13 +255,14 @@ The goals of this repo are to:
4. and keep the resultant file reasonably sized.
A high-quality source is defined here as one that is actively curated. A hosts source should be frequently
updated by its maintainers with both additions and removals. The larger the hosts file, the higher the level of
A high-quality source is defined here as one that is actively curated. A
hosts source should be frequently updated by its maintainers with both
additions and removals. The larger the hosts file, the higher the level of
curation is expected.
For example, the (huge) hosts file from [hosts-file.net](http://hosts-file.net) is **not** included
here because it is very large (300,000+ entries) and doesn't currently display a corresponding high level of curation
activity.
For example, the (huge) hosts file from [hosts-file.net](http://hosts-
file.net) is **not** included here because it is very large (300,000+ entries)
and doesn't currently display a corresponding high level of curation activity.
It is expected that this unified hosts file will serve both desktop and mobile devices under a variety of operating
systems.
It is expected that this unified hosts file will serve both desktop and mobile
devices under a variety of operating systems.