Vagrant plugin for ngrok
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
.gitignore
Gemfile
MIT-LICENSE
README.md
Rakefile
vagrant-foodshow.gemspec

README.md

Foodshow: Share your Vagrant virtual machine

Code Climate express42/vagrant-foodshow API Documentation

Vagrant-Foodshow plugin allows you to share tcp ports of your virtual machine via the Internet.

With this plugin you may show your web application to your colleague, present new feature for your customer and give ssh access to your ops guy.

All tunneling job performed by Ngrok backend. Ngrok tunnel can operate in TCP and HTTP modes. In HTTP tunnel mode ngrok provides access to HTTP requests and response from server to help you analyze the traffic. In TCP mode you can tunnel any binary protocol like ssh, postgresql or whatever you want, but there is no introspection in TCP tunnel.

Vagrant-foodshow and vagrant-share

Vagrant-foodshow unlike vagrnat-share an opensource product. Ngrok client and server part is also opensource. Ngrok server and server-side part of vagrant-share both available as SAAS solutions, but you can setup your own ngrok server for free. This is a good solution if you don't want send tunneled traffic through third-party servers.

Installation

Ngrok installation

You should go to ngrok.com and download ngrok binary for your system. Vagrant-foodshow will search ngrok binary in PATH. ~/bin/ngrok will be used if no ngrok binary in PATH. To disable search you may set foodshow.ngrok_bin option (See Advanced tunnel example).

Plugin installation

To install this plugin just execute:

vagrant plugin install vagrant-foodshow

Usage&Configuration

First of all you should enable plugin in your Vagrantfile:

config.foodshow.enabled = true

There are two ways to create a tunnel

Call method foodshow.tunnel :
...
config.foodshow.tunnel <host_port>, <protocol>, [options hash]
...
Add ngrok_proto parameter to vm.network :
...
config.vm.network :forwarded_port, guest: <guest_port>, host: <host_port>, ngrok_proto: "<protocol>"
...

Default tunnel protocol is http+https. Ngrok supports http, https, http+https and tcp. For tcp protocol authtoken is required.

Simple tunnel example

Vagrant.configure("2") do |config|
  #Enable foodshow
  config.foodshow.enabled = true
  ...
  # Define vm
  config.vm.define :web01 do |conf|
    ...
    #Just add ngrok_proto parameter to your port forwarding entry
    conf.vm.network :forwarded_port, guest: 80, host: 8080, ngrok_proto: "http+https"
    ...
    end
end

Advanced tunnel example

Vagrant.configure("2") do |config|
  #Enable foodshow
  config.foodshow.enabled = true
  # Change ngrok binary location
  config.foodshow.ngrok_bin = "/usr/local/bin/ngrok"
  # Automaticly search ssh port and create tcp tunnel
  config.foodshow.forward_ssh = true
  ...
  # Define vms
  config.vm.define :web01 do |conf|
    ...
    conf.vm.network :forwarded_port, guest: 80, host: 8080, ngrok_proto: "http+https"
    # Don't tunnel ssh for this vm
    config.foodshow.forward_ssh = false
    # For this vm we use another token
    conf.foodshow.authtoken = <sometoken_2>
    ...
  end
  config.vm.define :web02 do |conf|
    ...
    conf.vm.network :forwarded_port, guest: 80, host: 8081
    conf.vm.network :forwarded_port, guest: 389, host: 3389
    # You may pass some params as tunnel options
    # This code creates a tunnel http://mycopmanyllc.ngrok.com with basic auth
    conf.foodshow.tunnel 8081, "http", :httpauth => "foodshow:ngrok" :subdomain => "mycopmanyllc"
    # And sure you may tunnel any tcp port
    conf.foodshow.tunnel 3389, "tcp"
    ...
  end
end

Self-hosted tunnel example

Vagrant.configure("2") do |config|
  #Enable foodshow
  config.foodshow.enabled = true
  # Set your ngrokd server
  config.foodshow.server_addr = "127.0.0.1:4443"
  # Allow host root certificate
  config.foodshow.trust_host_root_certs = true
  ...
  # Define vm
  config.vm.define :web01 do |conf|
    ...
    #Just add ngrok_proto parameter to your port forwarding entry
    conf.vm.network :forwarded_port, guest: 80, host: 8080, ngrok_proto: "http+https"
    ...
    end
end

Read this document if you want to start self-hosted server https://github.com/inconshreveable/ngrok/blob/master/docs/SELFHOSTING.md

Options

  • Scope config means that this option can be set only via foodshow.<options>
  • Scope config+tunnel means that this option can be set via foodshow.<options> and can be can be passed to the foodshow.tunnel method as options hash.
  • Scope tunnel means that this option can be passed to the foodshow.tunnel method

Configuration options for ngrok v1.x

Option Default Scope Purpose
enabled false config Enable foodshow plugin
ngrok_bin nil config+tunnel By default vagrant-foodshow will search ngrok binary in PATH, then at ~/bin/ngrok. You may override this behavior by setting this option
forward_ssh false config Automatically search and forward vagrant ssh guest port (authtoken required)
timeout 10 config Max waiting time for establishing tunnel
authtoken nil config+tunnel Auth token. Required for TCP tunnels and some functions (Go to ngrok.com to get authkey)
httpauth nil config+tunnel You may set basic auth for http/https tunnel. Format: user:password
subdomain nil config+tunnel Custom subdomain for http/https tunnel. URL will be like a http://<subdomain>.ngrok.com
hostname nil config+tunnel Custom domain for http/https tunnel (Paid feature, see Pricing & Features on ngrok website )
host_ip 127.0.0.1 tunnel Custom destination ip for tunnel
inspect_addr 127.0.0.1 config Address for traffic inspection
inspect_pbase 4040 config Base port for traffic inspection, other ngrok processes will use the next available port
server_addr nil config+tunnel Server address for self-hosted ngrokd, see Self-hosted tunnels example
trust_host_root_certs nil config+tunnel Allow ngrok accept root server certificate. Must be true if you using self-hosted ngrokd

Changes in config options for ngrok v2.x

v1.x option v2.x option
httpauth => auth
inspect_addr => web_addr
inspect_pbase => web_pbase

If you are using ngrok v2.x authtoken option could be automatically filled from ngrok configuration

Authors

Contributing

  1. Fork it ( http://github.com/express42/vagrant-foodshow/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request