Skip to content

Latest commit

 

History

History
173 lines (117 loc) · 5.19 KB

README.md

File metadata and controls

173 lines (117 loc) · 5.19 KB
Raw

hostkeeper (WIP)

Current tag Repository issues Flattr this repository

hostkeeper is a Vagrant box that comes with a DNS server (dnsmasq) and a web interface to provide an easy way to manage network-wide DNS emulations (or modifications) during local web development phases. Usually you need to adjust the /etc/hosts file on your OS X or Windows machine to test your local project with productive domains. However, this approach won't work on a (non jailbreaked) iPhone which has no direct file system access. Once the DNS in your network settings is set to the IP of the hostkeeper Vagrant box, all DNS requests from said device will obey the "faked" ones from hostkeeper, hence you can surf via Safari to "http://reddit.com" but don't end up on the productive web server of reddit.com. Instead you end up on your local development box, since you added a mapping for that in the hostkeeper web interface.

Installation

Using Vagrant (recommended)

  1. Make sure you've installed Vagrant
  2. Clone this repository:
    git clone https://github.com/frdmn/hostkeeper
  3. Boot up the Vagrant box using:
    cd hostkeeper
    vagrant up
  4. Grab a coffee and wait about 6-7 minutes until hostkeeper has finished setting everything up. Keep an eye on the Vagrant provisioning script, it'll let you know as soon as it's done.
  5. Once completed, add your desired host/IP mappings in the hostkeeper web interface:
    http://192.168.1.79 (The guest system tries to setup an bridged network interface of your primary interface)
  6. Setup 192.168.1.79 as DNS server on any device where you want to use the adjusted/dummy/fake hostnames.

Without Vagrant

1. Prepare DNS (dnsmasq)

  1. Make sure you've installed dnsmasq

  2. Clone this repository:
    git clone https://github.com/frdmn/hostkeeper /opt/hostkeeper

  3. Adjust your dnsmasq configuration (/etc/dnsmasq.conf) so it'll load our hosts file:

    [...]
server=8.8.8.8
addn-hosts=/vagrant/db.dnsmasq

  4. Restart dnsmasq to activate the new configuration:
    service dnsmasq restart

2. Web interface
  1. Make sure you've installed grunt-cli and bower globally:
    npm install -g grunt-cli bower
  2. Install all Node dependencies in the public/ directory:
    cd /opt/hostkeeper
    npm install
  3. Install all libraries using Bower:
    bower install
  4. Run Grunt tasks to compile assets:
    grunt
3. RESTful API
  1. Copy default host database into project root:
    cp /opt/hostkeeper/vagrant-opt/db.example.json /opt/hostkeeper/db.json
  2. Create folders for pid and log files:
    mkdir -p /opt/hostkeeper/pid /opt/hostkeeper/log
  3. Run app.js to start web and API server (as root - if your dnsmasq runs as root):
    sudo node app.js
  4. Open the hostkeeper web interface and add some mappings:
    http://localhost

To test the functionality, you can directly query your local DNS server by running:

$ dig reddit.com @[hostkeeper] +short
192.168.1.100

As you can see, hostkeeper returns our adjusted (example) web server IP: 192.168.1.100

Usage

Install/setup/boot hostkeeper

$ vagrant up

In case you want to see stdout output of the commands running in the background:

$ HOSTKEEPER_DEBUG=true vagrant up

Recompile assets/node modules/bower components

In case you contribute and want to test your changes:

$ vagrant provision

Again, in case you want to see stdout output of the commands running in the background:

$ HOSTKEEPER_DEBUG=true vagrant up

Shutdown virtual machine

$ vagrant suspend

And if you want to power it up again:

https://github.com/frdmn/hostkeeper#installsetupboot-hostkeeper

Remove virtual machine

$ vagrant destroy

Architecture

hostkeeper consists out of three parts:

DNS

  • Heart of the hostkeeper project
  • Returns "modified" DNS requests for all clients

Web interface

  • Easy panel for users to add host/IP mappings
  • Communicates via REST API to rebuild dnsmasq hosts files and restart services
  • ExpressJS as static web server

RESTful API

  • REST using simple-node-router
  • Maintains the hosts database/storage
  • Turns database/storage into dnsmasq-compatible format
  • Restarts dnsmasq to reload new hosts

You can find a detailed API documentation here: API.md

Requirements / Dependencies

Using Vagrant

  • Vagrant

Without Vagrant

  • NodeJS
  • Grunt
  • Bower
  • dnsmasq

Version

0.2.0

Contributing

  1. Fork it
  2. Create your feature branch: git checkout -b feature/my-new-feature
  3. Commit your changes: git commit -am 'Add some feature'
  4. Push to the branch: git push origin feature/my-new-feature
  5. Submit a pull request

License

MIT