landrush 1.1.2 → 1.2.0

data/Rakefile

@@ -5,14 +5,18 @@ require 'rake/clean'
 require 'rubocop/rake_task'
 require 'cucumber/rake/task'
 require 'fileutils'
+require 'asciidoctor'
 
 CLOBBER.include('pkg')
 CLEAN.include('build')
 
 task :init do
+  # general build directory
   FileUtils.mkdir_p 'build'
+  # Vagrant home directory for integration tests
+  FileUtils.mkdir_p 'build/vagrant.d'
 end
-task :features => :init
+task features: :init
 
 # Default test task
 desc 'Run all unit tests'
@@ -23,7 +27,15 @@ end
 
 # Cucumber acceptance test task
 Cucumber::Rake::Task.new(:features)
-task :features => :init
+task features: :init
+
+desc 'Render Asciidoc into HTML'
+adoc_files = Rake::FileList['**/*.adoc']
+task html: adoc_files.ext('.html')
+rule '.html' => '.adoc' do |t|
+  FileUtils.mkdir_p 'build/html'
+  Asciidoctor.convert_file t.source, to_dir: 'build/html'
+end
 
 task default: [
   :rubocop,

data/appveyor.yml

@@ -0,0 +1,20 @@
+# Landrush CI configuration for AppVeyor
+---
+version: "{build}"
+branches:
+  only:
+    - master
+install:
+  - set PATH=C:\Ruby22\bin;%PATH%
+  - ruby --version
+  - gem --version
+  - gem uninstall -x bundler
+  - gem install bundler -v 1.12.5
+  - bundler --version
+  - bundle install
+build_script:
+  - bundle exec rake clean install
+test_script:
+  - bundle exec rake rubocop test TESTOPTS="-v"
+artifacts:
+  - path: pkg\*.gem

data/doc/Development.adoc

@@ -0,0 +1,112 @@
+= Development
+:toc:
+:toc-placement!:
+
+The following should get you started on setting up your development environment. As a prerequisite you will need a Ruby 2.2 environment. We
+recommend to use https://rvm.io/[RVM] to create an isolated development
+environment. On Windows the http://rubyinstaller.org/[RubyInstaller for
+Windows] is probably the easiest way to get started. In this case you
+will need the http://rubyinstaller.org/add-ons/devkit/[DevKit] as well.
+
+'''
+toc::[]
+'''
+
+Once you have a working Ruby environment it is time to
+https://help.github.com/articles/fork-a-repo/[fork] the repository. Refer to the link:../CONTRIBUTING.adoc[Contributing] guide for more information.
+
+The following sections list the most important commands you will need for
+development.
+
+== Setup
+
+* Install http://bundler.io/[Bundler]:
++
+....
+$ gem install bundler
+....
+* Install dependencies:
++
+....
+$ bundle install
+....
+* Get a list of all available build tasks:
++
+....
+$ bundle exec rake -T
+....
+
+* Build the Landrush gem:
++
+....
+$ bundle exec rake install
+....
+* Clean all generated files:
++
+....
+$ bundle exec rake clean clobber
+....
+
+== Tests
+
+* Run the test suite:
++
+....
+$ bundle exec rake test
+....
+* Run a single test file:
++
+....
+$ bundle exec rake test TEST=<path to test file>
+....
+* Run cucumber/aruba acceptance tests:
++
+....
+$ bundle exec rake features
+....
+
+NOTE: The acceptance tests currently work only for OS X, out of the box.
+On Linux, one has to manually configure the host visibility for the
+TLD _landrush-acceptance-test_. See *Linux* in the *Visibility on the Host* section of the link:Usage.adoc[Usage guide]. On Windows,
+the acceptance tests won't work due to a bug in
+https://github.com/cucumber/aruba/issues/387[Aruba].
+
+* Run a single cucumber/aruba acceptance tests:
++
+....
+$ bundle exec rake features FEATURE=features/<feature-filename>.feature
+....
+
+== Documentation
+
+The documentation of this plugin is written in http://asciidoctor.org[Asciidoc]. If you need some syntax help,
+refer to the http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[AsciiDoc Syntax Quick Reference].
+
+To build the documentation you can execute
+
+----
+$ bundle exec rake html
+----
+
+which will build the HTML documentation into the folder _build/html_.
+
+The source code also contains a link:../Guardfile[Guardfile] for the https://github.com/guard/guard[Guard] library.
+You can execute
+
+----
+$ bundle exec guard
+----
+
+and your HTML documentation will be automatically updated on each change to an Asciidoc source file.
+https://github.com/guard/guard-livereload[Live reload] is also enabled, so you just need to install the right
+http://livereload.com/extensions/#installing-sections[LiveReload Safari/Chrome/Firefox extension] and your
+browser can refresh the page each time you save a change to your Asciidoc files.
+
+== Misc
+
+* Run the vagrant binary with the Landrush plugin loaded from your local
+source code:
++
+....
+bundle exec vagrant landrush <command>
+....

data/doc/ProxyMobile.adoc

@@ -0,0 +1,66 @@
+= Resolve Landrush entries on a mobile device
+:toc:
+:toc-placement!:
+
+'''
+toc::[]
+'''
+
+For your mobile phone to access VM-hosts two conditions need to be met:
+
+* Your VM _needs to be accessible_ from the network your phone's on
+(configure a http://docs.vagrantup.com/v2/networking/public_network.html[public network]).
+* The phone should query Landrush to resolve DNS entries.
+
+Most smartphones allow you to configure a custom DNS server (instructions further below),
+but unfortunately some don't allow you to configure a DNS server running on port 10053.
+
+To work around that one can proxy queries to the default port 53 with a system-wide DNS server to Landrush.
+
+== Proxy bind to your Landrush server
+
+The DNS-server `bind` can be installed with http://brew.sh/[homebrew] on
+OS X.
+
+In its configuration file forward all queries to your local Landrush and
+disable caching:
+
+....
+options {
+    directory "/usr/local/var/named";
+
+    forwarders {
+        127.0.0.1 port 10053;
+    };
+
+    max-cache-ttl 0;
+    max-ncache-ttl 0;
+};
+....
+
+After restarting bind you should be able to resolve your VM's entries on
+your local default DNS server (port 53):
+
+....
+$ dig -p 53 @localhost myhost.vagrant.test
+....
+
+== Configure DNS server on your mobile phone
+
+Set your bind server's IP address as the DNS server on your external device.
+
+=== How to set the DNS server on iOS
+
+.  Open _Settings_ > _Wi-Fi_
+.  Tap the _i_-icon next to your network
+.  Tap the _DNS_-row and edit the value
+
+=== How to set the DNS server on Android
+
+.  Open _Settings_ > _Wi-Fi_
+.  Tap and hold your network, then chose _Modify network_
+.  Check _Show advanced options_
+.  Under _IP Settings_ tap _DHCP / Static_ and change the value to _Static_
+.  Change the _DNS 1_ value and tap _Save_
+
+Or use the https://play.google.com/store/apps/details?id=net.emrekoc.dnschanger[Dns Changer] application.

data/doc/Troubleshooting.adoc

@@ -0,0 +1,42 @@
+= Troubleshooting
+:toc:
+:toc-placement!:
+
+Use this guide to resolve basic Landrush issues you run into.
+
+'''
+toc::[]
+'''
+
+== How to avoid providing sudo password on OS X
+
+When using Landrush on OS X, Landrush will try to create a file in
+`/etc/resolver` to make the guest VM visible via DNS on the host. See *OS X* in the *Visibility on the Host* section of the link:Usage.adoc[Usage guide]. To create this file, sudo permissions are needed and Landrush
+will ask you for your sudo password. +
+ +
+This can be avoided by adding the
+following entries to the bottom of the sudoer configuration. Make sure
+to edit your `/etc/sudoers` configuration via `sudo visudo`:
+
+....
+# Begin Landrush config
+Cmnd_Alias VAGRANT_LANDRUSH_HOST_MKDIR = /bin/mkdir /etc/resolver/*
+Cmnd_Alias VAGRANT_LANDRUSH_HOST_CP = /bin/cp /*/vagrant_landrush_host_config* /etc/resolver/*
+Cmnd_Alias VAGRANT_LANDRUSH_HOST_CHMOD = /bin/chmod 644 /etc/resolver/*
+%admin ALL=(ALL) NOPASSWD: VAGRANT_LANDRUSH_HOST_MKDIR, VAGRANT_LANDRUSH_HOST_CP, VAGRANT_LANDRUSH_HOST_CHMOD
+# End Landrush config
+....
+
+== Guest is unable to access the Internet
+
+In some network configurations the access to outside DNS servers is
+restricted (firewalls, VPN, etc). Since unmatched DNS queries are per
+default passed through to Google's DNS servers, this can lead to the
+fact that the guest cannot access anything in the outside world. +
+ +
+If you face problem with the guest's DNS, verify that you can access
+Google's DNS server under __8.8.8.8__. If it does not work, you will
+need to set a custom upstream DNS server. Check your network
+configuration on the host or ask your network administrator about the
+right DNS server address to use. You can set the custom DNS server via
+the `config.landrush.upstream` option, see section on *Unmatched Queries* in the link:Usage.adoc[Usage guide].

data/doc/Usage.adoc

@@ -0,0 +1,271 @@
+= Usage
+:toc:
+:toc-placement!:
+
+The following sections explain how you can use the Landrush DNS server and customize it as per your requirements, once you have link:README.adoc[installed] it.
+
+'''
+toc::[]
+'''
+
+== Dynamic entries
+
+Every time a VM is started, its IP address is automatically detected and
+a DNS record is created that maps the hostname to its IP. The detection
+works by listing all configured interfaces of the guest using
+https://rubygems.org/gems/landrush-ip/versions/0.2.5[landrush-ip],
+picking the last valid IP found, while ignoring any excluded interfaces.
+
+Excluded interfaces are an array of regular expressions; the value shown
+here is the default used when no explicit value for
+`config.landrush.host_interface_excludes` is specified in your
+`Vagrantfile`:
+
+....
+config.landrush.host_interface_excludes = [/lo[0-9]*/, /docker[0-9]+/, /tun[0-9]+/]
+....
+
+If Landrush fails to detect the correct IP address (or none at all), you
+can extend this exclusion range to exclude more interfaces.
+
+You can also make sure to only select a specific class of IP address
+(`:ipv4`, `:ipv6` or `:any`). Either way, empty values will not be
+returned, but in the case of `:any` you may get the IPv6 address for an
+interface that has no IPv4 address. The default is to return the first
+non-empty IPv4 address:
+
+....
+config.landrush.host_interface_class = :ipv4
+....
+
+If you need or want to select an interface explicitly and you know its
+name, you can also tell Landrush to grab that interface's IP address
+explicitly:
+
+....
+config.landrush.host_interface = 'eth0'
+....
+
+NOTE: If you specify an interface explicitly, it will have
+priority over `config.landrush.host_interface_excludes`. In other words,
+if `config.landrush.host_interface_excludes` is set to `[/eth[0-9]*/]`,
+but `config.landrush.host_interface` is set to `eth0` and `eth0` exists
+as an interface, the IP address of `eth0` is returned. The interface
+setting takes precedence over the exclude setting. If the interface does
+not exist, the regular heuristics will apply and Landrush will pick the
+last non-excluded IP found.
+
+If all else fails, you can override it entirely:
+
+....
+config.landrush.host_ip_address = '1.2.3.4'
+....
+
+This setting will override both the exclude and interface settings
+completely.
+
+If you are using a multi-machine `Vagrantfile`, configure this inside
+each of your `config.vm.define` sections.
+
+== Static entries
+
+You can add static host entries to the DNS server in your `Vagrantfile`
+like so:
+
+....
+config.landrush.host 'myhost.example.com', '1.2.3.4'
+....
+
+This is great for overriding production services for nodes you might be
+testing locally. For example, perhaps you might want to override the
+hostname of your puppetmaster to point to a local vagrant box instead.
+
+== Wildcard Subdomains
+
+For your convenience, any subdomain of a DNS entry known to Landrush
+will resolve to the same IP address as the entry. For example, given
+`myhost.vagrant.test -> 1.2.3.4`, both `foo.myhost.vagrant.test` and
+`bar.myhost.vagrant.test` will also resolve to `1.2.3.4`.
+
+If you would like to configure your guests to be accessible from the
+host as subdomains of something other than the default `vagrant.test`,
+you can use the `config.landrush.tld` option in your Vagrantfile like
+so:
+
+....
+config.landrush.tld = 'vm'
+....
+
+NOTE: From the **host**, you will only be able to access subdomains
+of your configured TLD by default, so wildcard subdomains only apply to
+that space. For the **guest**, wildcard subdomains work for anything.
+
+== Unmatched Queries
+
+Any DNS queries that do not match any of Landrush's configuration data,
+will be passed through to an upstream DNS server. Per default Landrush
+uses Google's DNS server with the IP __8.8.8.8__.
+
+If you would like to configure your own upstream servers, add upstream
+entries to your `Vagrantfile` like so:
+
+....
+config.landrush.upstream '10.1.1.10'
+# Set the port to 1001
+config.landrush.upstream '10.1.2.10', 1001
+# If your upstream is TCP only for some strange reason
+config.landrush.upstream '10.1.3.10', 1001, :tcp
+....
+
+== Visibility on the Guest
+
+Linux guests should automatically have their DNS traffic redirected via
+`iptables` rules to the Landrush DNS server. File an issue if this does
+not work for you.
+
+To disable this functionality:
+
+....
+config.landrush.guest_redirect_dns = false
+....
+
+You may want to do this if you are already proxying all your DNS
+requests through your host (for example, using VirtualBox's natdnshostresolver1
+option) and you have DNS servers that you can easily set as upstreams in
+the daemon (for example, DNS requests that go through the host's VPN
+connection).
+
+== Visibility on the Host
+
+Visibility on the host means that the hostname of the VMs can be
+resolved on the host's DNS system. Landrush will attempt an automatic
+configuration of the host, but depending on the OS, manual configuration
+might be required as well.
+
+To disable this functionality:
+
+....
+config.landrush.host_redirect_dns = false
+....
+
+* OS X
++
+If you are on an OS X host, we use a nice trick to unobtrusively add a
+secondary DNS server only for specific domains. During startup Landrush automatically adds
+a file into `/etc/resolver` that points
+lookups for hostnames ending in your `config.landrush.tld` domain to its
+DNS server. (See `man 5 resolver` on your Mac OS X host for more
+information on this file's syntax.)
+
+* Linux
++
+Landrush tries to achieve the same behavior on Linux hosts using
+`dnsmasq`. For some Linux distributions this happens automatically (you
+might have to provide your _sudo_ password). If Landrush does not know
+how to install and start `dnsmasq` on your favorite Linux distribution,
+you can adjust the following example from Ubuntu:
++
+....
+sudo apt-get install -y resolvconf dnsmasq
+sudo sh -c 'echo "server=/vagrant.test/127.0.0.1#10053" > /etc/dnsmasq.d/vagrant-landrush'
+sudo service dnsmasq restart
+....
++
+If you use a TLD other than the default `vagrant.test`, replace the TLD
+in the above instructions accordingly. Please be aware that anything
+ending in `.local` as TLD will not work because the `avahi` daemon
+reserves this TLD for its own uses.
+
+* Windows
++
+On Windows a secondary DNS server can be configured via the properties
+of the network adapter used by the VM. Landrush will attempt to
+configure the adapter automatically during startup. If this fails,
+please follow the manual setup instructions below.
++
+It is recommended to use an elevated command prompt (command prompt with
+full administrator permissions), since admin privileges are needed to
+make the required changes. Landrush will try to elevate your prompt
+automatically, but this requires spawning of additional processes which in
+turn loose some potentially important log messages.
++
+In the following section manual network configuration is described using
+Windows 10 and VirtualBox.
++
+When running VirtualBox on Windows in combination with Landrush the
+Network Connections
+(`Control Panel\Network and Internet\Network Connections`) looks
+somewhat like this after a successful `vagrant up`: +
+ +
++
+image:img/network-connections.png[Network
+Connections,title="Network Connections"] +
+ +
+There will be at least one VirtualBox network adapter. There might be
+multiple depending on your configuration (number of networks configured)
+and how many VMs you have running, but you just need to modify one.
++
+In a first step, you need to identify the VirtualBox network adapter used
+for the private network of your VM. Landrush requires a private network
+adapter to work and will create one in case you are not explicitly
+configuring one in your `Vagrantfile`.
++
+To quickly view the settings of each network adapter you can run the
+following command in a shell:
++
+....
+netsh interface ip show config
+....
++
+The output should look something like this:
++
+....
+Configuration for interface "Ethernet0"
+    DHCP enabled:                         Yes
+    IP Address:                           172.16.74.143
+    Subnet Prefix:                        172.16.74.0/24 (mask 255.255.255.0)
+    Default Gateway:                      172.16.74.2
+    Gateway Metric:                       0
+    InterfaceMetric:                      10
+    DNS servers configured through DHCP:  172.16.74.2
+    Register with which suffix:           Primary only
+    WINS servers configured through DHCP: 172.16.74.2
+
+Configuration for interface "VirtualBox Host-Only Network"
+    DHCP enabled:                         No
+    IP Address:                           10.1.2.1
+    Subnet Prefix:                        10.1.2.0/24 (mask 255.255.255.0)
+    InterfaceMetric:                      10
+    Statically Configured DNS Servers:    None
+    Register with which suffix:           Primary only
+    Statically Configured WINS Servers:   None
+....
++
+In our case we are interested in the `VirtualBox Host-Only Network`
+which has in this example the private network IP 10.1.2.1. If you do not
+have a static private network IP configured and you cannot determine the
+right adapter via the `netsh` output, ssh into the VM (`vagrant ssh`)
+and run `ifconfig` to view the network configuration of the VM.
++
+Once you identified the right network adapter run the following as
+Administrator (using the network adapter name of the adapter with the
+determined private network IP):
++
+....
+ netsh interface ipv4 add dnsserver "VirtualBox Host-Only Network" address=127.0.0.1 index=1
+....
++
+This should be enough for Windows 10. On other Windows versions, you
+might have to also add your TLD to the DNS suffix list on the DNS
+Advanced TCP/IP Settings tab: +
+ +
+image:img/advanced-tcp-properties.png[Advanced TCP/IP
+Settings,title="Advanced TCP/IP Settings"] +
+ +
+* Other Devices (phone)
++
+You might want to resolve Landrush's DNS-entries on _additional_
+computing devices, like a mobile phone.
+Please refer to link:ProxyMobile.adoc[mobile instructions] for further details.
+
+You can refer to the link:Troubleshooting.adoc[Troubleshooting guide] if you encounter any problems while using Landrush.