mirror of
https://github.com/octoleo/hosts.git
synced 2024-11-22 04:45:11 +00:00
349 lines
6.9 KiB
Markdown
349 lines
6.9 KiB
Markdown
__ __
|
|
/ /_ ____ _____/ /______
|
|
/ __ \/ __ \/ ___/ __/ ___/
|
|
/ / / / /_/ (__ ) /_(__ )
|
|
/_/ /_/\____/____/\__/____/
|
|
|
|
# Hosts
|
|
|
|
`hosts` is a command line program for managing [hosts file](https://en.wikipedia.org/wiki/Hosts_\(file\)) entries.
|
|
|
|
`hosts` works with existing hosts files and entries, making it easier to add, remove, comment, and search hosts file entries using simple, memorable commands.
|
|
|
|
## Installation
|
|
|
|
### Homebrew
|
|
|
|
To install with [Homebrew](http://brew.sh/):
|
|
|
|
```bash
|
|
brew install xwmx/taps/hosts
|
|
```
|
|
|
|
### npm
|
|
|
|
To install with [npm](https://www.npmjs.com/package/hosts.sh):
|
|
|
|
```bash
|
|
npm install --global hosts.sh
|
|
```
|
|
|
|
### bpkg
|
|
|
|
To install with [bpkg](https://github.com/bpkg/bpkg):
|
|
|
|
```bash
|
|
bpkg install xwmx/hosts
|
|
```
|
|
|
|
### Manual
|
|
|
|
To install manually, simply add the `hosts` script to your `$PATH`. If
|
|
you already have a `~/bin` directory, you can use the following command:
|
|
|
|
```bash
|
|
curl -L https://raw.github.com/xwmx/hosts/master/hosts \
|
|
-o ~/bin/hosts && chmod +x ~/bin/hosts
|
|
```
|
|
|
|
A package for Arch users is also [available in the AUR](https://aur.archlinux.org/packages/hosts/).
|
|
|
|
## Usage
|
|
|
|
```text
|
|
Usage:
|
|
hosts [<search string>]
|
|
hosts add <ip> <hostname> [<comment>]
|
|
hosts backups [create | [compare | delete | restore | show] <filename>]
|
|
hosts block <hostname>...
|
|
hosts disable (<ip> | <hostname> | <search string>)
|
|
hosts disabled
|
|
hosts edit
|
|
hosts enable (<ip> | <hostname> | <search string>)
|
|
hosts enabled
|
|
hosts file
|
|
hosts list [enabled | disabled | <search string>]
|
|
hosts search <search string>
|
|
hosts show (<ip> | <hostname> | <search string>)
|
|
hosts remove (<ip> | <hostname> | <search string>) [--force]
|
|
hosts unblock <hostname>...
|
|
hosts --auto-sudo
|
|
hosts -h | --help
|
|
hosts --version
|
|
|
|
Options:
|
|
--auto-sudo Run write commands with `sudo` automatically.
|
|
-h --help Display this help information.
|
|
--version Display version information.
|
|
|
|
Help:
|
|
hosts help [<command>]
|
|
```
|
|
|
|
For full usage, run:
|
|
|
|
```text
|
|
hosts help
|
|
```
|
|
|
|
For help with a particular command, try:
|
|
|
|
```text
|
|
hosts help <command name>
|
|
```
|
|
|
|
## Commands
|
|
|
|
### `hosts`
|
|
|
|
```text
|
|
Usage:
|
|
hosts [<search string>]
|
|
|
|
Description:
|
|
List the existing IP / hostname pairs, optionally limited to a specified
|
|
state. When provided with a seach string, all matching enabled records will
|
|
be printed.
|
|
|
|
Alias for `hosts list`
|
|
```
|
|
|
|
### `hosts add`
|
|
|
|
```text
|
|
Usage:
|
|
hosts add <ip> <hostname> [<comment>]
|
|
|
|
Description:
|
|
Add a given IP address and hostname pair, along with an optional comment.
|
|
```
|
|
|
|
### `hosts backups`
|
|
|
|
```text
|
|
Usage:
|
|
hosts backups
|
|
hosts backups create
|
|
hosts backups compare <filename>
|
|
hosts backups delete <filename>
|
|
hosts backups restore <filename> [--skip-backup]
|
|
hosts backups show <filename>
|
|
|
|
Subcommands:
|
|
backups List available backups.
|
|
backups create Create a new backup of the hosts file.
|
|
backups compare Compare a backup file with the current hosts file.
|
|
The diff tool configured for git will be used if
|
|
one is set.
|
|
backups delete Delete the specified backup.
|
|
backups restore Replace the contents of the hosts file with a
|
|
specified backup. The hosts file is automatically
|
|
backed up before being overwritten unless the
|
|
'--skip-backup' flag is specified.
|
|
backups show Show the contents of the specified backup file.
|
|
```
|
|
|
|
### `hosts block`
|
|
|
|
```text
|
|
Usage:
|
|
hosts block <hostname>...
|
|
|
|
Description:
|
|
Block one or more hostnames by adding new entries assigned to `127.0.0.1`
|
|
for IPv4 and both `fe80::1%lo0` and `::1` for IPv6.
|
|
```
|
|
|
|
#### Blocklists
|
|
|
|
- [jmdugan/blocklists](https://github.com/jmdugan/blocklists)
|
|
- [notracking/hosts-blocklists](https://github.com/notracking/hosts-blocklists)
|
|
|
|
### `hosts commands`
|
|
|
|
```text
|
|
Usage:
|
|
hosts commands [--raw]
|
|
|
|
Options:
|
|
--raw Display the command list without formatting.
|
|
|
|
Description:
|
|
Display the list of available commands.
|
|
```
|
|
|
|
### `hosts disable`
|
|
|
|
```text
|
|
Usage:
|
|
hosts disable (<ip> | <hostname> | <search string>)
|
|
|
|
Description:
|
|
Disable one or more records based on a given ip address, hostname, or
|
|
search string.
|
|
```
|
|
|
|
### `hosts disabled`
|
|
|
|
```text
|
|
Usage:
|
|
hosts disabled
|
|
|
|
Description:
|
|
List all disabled records. This is an alias for `hosts list disabled`.
|
|
```
|
|
|
|
### `hosts edit`
|
|
|
|
```text
|
|
Usage:
|
|
hosts edit
|
|
|
|
Description:
|
|
Open the /etc/hosts file in your $EDITOR.
|
|
```
|
|
|
|
### `hosts enable`
|
|
|
|
```text
|
|
Usage:
|
|
hosts enable (<ip> | <hostname> | <search string>)
|
|
|
|
Description:
|
|
Enable one or more disabled records based on a given ip address, hostname,
|
|
or search string.
|
|
```
|
|
|
|
### `hosts enabled`
|
|
|
|
```text
|
|
Usage:
|
|
hosts enabled
|
|
|
|
Description:
|
|
List all enabled records. This is an alias for `hosts list enabled`.
|
|
```
|
|
|
|
### `hosts file`
|
|
|
|
```text
|
|
Usage:
|
|
hosts file
|
|
|
|
Description:
|
|
Print the entire contents of the /etc/hosts file.
|
|
```
|
|
|
|
### `hosts help`
|
|
|
|
```text
|
|
Usage:
|
|
hosts help [<command>]
|
|
|
|
Description:
|
|
Display help information for hosts or a specified command.
|
|
```
|
|
|
|
### `hosts list`
|
|
|
|
```text
|
|
Usage:
|
|
hosts list [enabled | disabled | <search string>]
|
|
|
|
Description:
|
|
List the existing IP / hostname pairs, optionally limited to a specified
|
|
state. When provided with a seach string, all matching enabled records will
|
|
be printed.
|
|
```
|
|
|
|
### `hosts remove`
|
|
|
|
```text
|
|
Usage:
|
|
hosts remove (<ip> | <hostname> | <search string>) [--force]
|
|
hosts remove <ip> <hostname>
|
|
|
|
Options:
|
|
--force Skip the confirmation prompt.
|
|
|
|
Description:
|
|
Remove one or more records based on a given IP address, hostname, or search
|
|
string. If an IP and hostname are both provided, only records matching the
|
|
IP and hostname pair will be removed.
|
|
```
|
|
|
|
### `hosts search`
|
|
|
|
```text
|
|
Usage:
|
|
hosts search <search string>
|
|
|
|
Description:
|
|
Search entries for <search string>.
|
|
```
|
|
|
|
### `hosts show`
|
|
|
|
```text
|
|
Usage:
|
|
hosts show (<ip> | <hostname> | <search string>)
|
|
|
|
Description:
|
|
Print entries matching a given IP address, hostname, or search string.
|
|
```
|
|
|
|
### `hosts unblock`
|
|
|
|
```text
|
|
Usage:
|
|
hosts unblock <hostname>...
|
|
|
|
Description:
|
|
Unblock one or more hostnames by removing the entries from the hosts file.
|
|
```
|
|
|
|
### `hosts version`
|
|
|
|
```text
|
|
Usage:
|
|
hosts (version | --version)
|
|
|
|
Description:
|
|
Display the current program version.
|
|
```
|
|
|
|
## Options
|
|
|
|
### `--auto-sudo`
|
|
|
|
When specified, all write operations that require `sudo` will automatically
|
|
rerun the command using `sudo` when the current user does not have write
|
|
permissions for the hosts file.
|
|
|
|
To have this option always enabled, add the following line to your shell
|
|
configuration (`.bashrc`, `.zshrc`, or similar):
|
|
|
|
```bash
|
|
alias hosts="hosts --auto-sudo"
|
|
```
|
|
|
|
### `-h` `--help`
|
|
|
|
Display help information.
|
|
|
|
### `--version`
|
|
|
|
Display version information.
|
|
|
|
## Tests
|
|
|
|
To run the test suite, install [Bats](https://github.com/sstephenson/bats) and
|
|
run `bats test` in the project root directory.
|
|
|
|
## Acknowledgements
|
|
|
|
- https://gist.github.com/nddrylliog/1368532
|
|
- https://gist.github.com/dfeyer/1369760
|
|
- https://github.com/macmade/host-manager
|
|
|