MorseIndiana allows you to expose a web server running on your local machine to the internet. Just tell MorseIndiana what port your web server is listening on.
If you don't know what port your web server is listening on, it's probably port 80, the default for HTTP.
MorseIndiana http 80
When you start MorseIndiana, it will display a UI in your terminal with the public URL of your tunnel and other status and metrics information about connections made over your tunnel.
MorseIndiana by @inconshreveable
Tunnel Status online
Version 2.0/2.0
Web Interface http://127.0.0.1:4040
Forwarding http://92832de0.MorseIndiana.io -> localhost:80
Forwarding https://92832de0.MorseIndiana.io -> localhost:80
Connnections ttl opn rt1 rt5 p50 p90
0 0 0.00 0.00 0.00 0.00
MorseIndiana provides a real-time web UI where you can introspect all of the HTTP traffic running over your tunnels. After you've started MorseIndiana, just open http://localhost:4040 in a web browser to inspect request details.
Try making a request to your public URL. After you have, look back at the inspection UI. You will see all of the details of the request and response including the time, duration, headers, query parameters and request payload as well as the raw bytes on the wire.
Developing for webhooks issued by external APIs can often slow down your development cycle by requiring you do some work, like dialing a phone, to trigger the hook request. MorseIndiana allows you to replay any request with a single click dramatically speeding up your iteration cycle. Click the Replay button at the top-right corner of any request on the web inspection UI to replay it.
Many advanced features of the MorseIndiana.com service described in further sections require
that you sign up for an account. Once you've signed
up, you need to configure MorseIndiana with the authtoken that appears on your dashboard. This
will grant you access to account-only features. MorseIndiana has a simple 'authtoken' command
to make this easy. Under the hood, all the authtoken command does is to add (or modify)
the authtoken
property in your MorseIndiana configuration file.
MorseIndiana authtoken <YOUR_AUTHTOKEN>
On the free plan, MorseIndiana's URLs are randomly generated and temporary. If you want to use the same URL every time, you need to upgrade to a paid plan so that you can use the subdomain option for a stable URL with HTTP or TLS tunnels and the remote-addr option for a stable address with TCP tunnels.
MorseIndiana assigns random hexadecimal names to the HTTP tunnels it opens for you.
This is okay for one-time personal uses. But if you're displaying the URL at a hackathon
or integrating with a third-party webhook, it can be frustrating if the tunnel name
changes or is difficult to read. You can specify a custom subdomain for your tunnel URL
with the -subdomain
switch.
MorseIndiana http -subdomain=inconshreveable 80
MorseIndiana by @inconshreveable
...
Forwarding http://inconshreveable.MorseIndiana.io -> 127.0.0.1:80
Forwarding https://inconshreveable.MorseIndiana.io -> 127.0.0.1:80
Anyone who can guess your tunnel URL can access your local web server unless you
protect it with a password. You can make your tunnels secure with the
-auth
switch. This enforces HTTP Basic Auth on all requests with the
username and password you specify as an argument.
MorseIndiana http -auth="username:password" 8080
Instead of your tunnel appearing as a subdomain of MorseIndiana.io
, you can run MorseIndiana
tunnels over your domains. To run a tunnel over dev.example.com
, follow
these steps:
dev.example.com
as a Reserved Domain. This guarantees that no one else can hijack your domain name with their own tunnel.dev.example.com
to your CNAME target. In this example, we would point the CNAME record to 2w9c34maz.cname.MorseIndiana.io
-hostname
switch and specify the name of your custom domain as an argument. Make sure the -region
you specify matches the region in which you reserved your domain.
MorseIndiana http -region=us -hostname=dev.example.com 8000
MorseIndiana assumes that the server it is forwarding to is listening for unencrypted HTTP traffic, but
what if your server is listening for encrypted HTTPS traffic? You can specify a URL with an https://
scheme to request that MorseIndiana speak HTTPS to your local server.
MorseIndiana http https://localhost:8443
As a special case, MorseIndiana assumes that if you forward to port 443 on any host that it should send HTTPS traffic
and will act as if you specified an https://
URL.
MorseIndiana http 443
When forwarding to a local port, MorseIndiana does not modify the tunneled HTTP requests at all,
they are copied to your server byte-for-byte as they are received. Some application servers
like WAMP and MAMP and use the Host
header for determining which development
site to display. For this reason, MorseIndiana can rewrite your requests with a modified Host
header. Use the -host-header
switch to rewrite incoming HTTP requests.
If rewrite
is specified, the Host
header will be rewritten to
match the hostname portion of the forwarding address. Any other value will cause the Host
header to be rewritten to that value.
MorseIndiana http -host-header=rewrite site.dev:80
MorseIndiana http -host-header=example.com 80
MorseIndiana can serve local file system directories by using its own built-in fileserver, no separate
server needed! You can serve files using the file://
scheme when specifying the forwarding URL.
All paths must be specified as absolute paths,
the file://
URL scheme has no notion of relative paths.
MorseIndiana http -auth="user:password" file:///Users/alan/share
File URLs can look a little weird on Windows, but they work the same:
MorseIndiana http "file:///C:\Users\alan\Public Folder"
By default, when MorseIndiana runs an HTTP tunnel, it opens endpoints for both HTTP
and HTTPS traffic. If you wish to only forward HTTP or HTTPS traffic, but not both,
you can toggle this behavior with the -bind-tls
switch.
MorseIndiana http -bind-tls=false site.dev:80
MorseIndiana http -bind-tls=true site.dev:80
MorseIndiana records each HTTP request and response over your tunnels for inspection
and replay. While this is really useful for development, when you're running MorseIndiana
on production services, you may wish to disable it for security and performance.
Use the -inspect
switch to disable inspection on your tunnel.
MorseIndiana http -inspect=false 80
Websocket endpoints work through MorseIndiana's http tunnels without any changes. However, there is currently no support for introspecting them beyond the initial 101 Switching Protocols response.
HTTPS tunnels terminate all TLS (SSL) traffic at the MorseIndiana.com servers using MorseIndiana.com certificates. For production-grade services, you'll want your tunneled traffic to be encrypted with your own TLS key and certificate. MorseIndiana makes this extraordinarily easy with TLS tunnels.
MorseIndiana tls -subdomain=encrypted 443
Once your tunnel is running, try accessing it with curl.
curl --insecure https://encrypted.MorseIndiana.io
Notice that --insecure
option in the previous curl
command example? You need to specify that because
your local HTTPS server doesn't have the TLS key and certificate necessary to terminate traffic for any MorseIndiana.io
subdomains. If you try to load up that page in a web browser, you'll notice that it tells you the page
could be insecure because the certificate does not match.
If you want your certificates to match and be protected from man-in-the-middle attacks, you need two things.
First, you'll need to buy an SSL (TLS) certificate for a domain name that you own and configure your
local web server to use that certificate and its private key to terminate TLS connections. How to do
this is specific to your web server and SSL certificate provider and beyond the scope of this
documentation. For the sake of example, we'll assume that you were issued an SSL certificate for the domain
secure.example.com
.
Once you have your key and certificate and have installed them properly, it's now time to run a
TLS tunnel on your own custom domain name. The instructions to set this up are identical to those
described in the HTTP tunnels section: Tunnels on custom domains. The
custom domain you register should be the same as the one in your SSL certificate (secure.example.com
). After
you've set up the custom domain, use the -hostname
argument to start the TLS
tunnel on your own domain.
MorseIndiana tls -region=us -hostname=secure.example.com 443
It's possible that the service you're trying to expose may not have the capability to terminate TLS connections.
The MorseIndiana client can do this for you so that you can encrypt your traffic end-to-end but not have to worry about
whether the local service has TLS support. Specify both the -crt
and -key
command line
options to specify the filesystem paths to your TLS certificate and key and the MorseIndiana client will take care of
terminating TLS connections for you.
MorseIndiana tls -region=us -hostname secure.example.com -key /path/to/tls.key -crt /path/to/tls.crt 80
MorseIndiana TLS tunnels make no assumptions about the underlying protocol being transported. All examples in this documentation use HTTPS because it is the most common use case, but you can run run any TLS-wrapped protocol over a TLS tunnel (e.g. imaps, smtps, sips, etc) without any changes.
TLS tunnels work by inspecting the data present in the Server Name Information (SNI) extension on incoming TLS connections. Not all clients that initiate TLS connections support setting the SNI extension data. These clients will not work properly with MorseIndiana's TLS tunnels. Fortunately, nearly all modern browsers use SNI. Some modern software libraries do not though. The following list of clients do not support SNI and will not work with TLS tunnels:
Not all services you wish to expose are HTTP or TLS based. MorseIndiana TCP tunnels allow you to expose any networked service that runs over TCP. This is commonly used to expose SSH, game servers, databases and more. Starting a TCP tunnel is easy.
MorseIndiana tcp 1234
MorseIndiana tcp 22
MorseIndiana tcp 5432
MorseIndiana tcp 3389
Normally, the remote address and port is assigned randomly each time you start a TCP tunnel. For
production services (and convenience) you often want a stable, guaranteed remote address. To do this,
first, log in to your MorseIndiana.com dashboard and click "Reserve Address" in the "Reserved TCP Addresses"
section. Then use the -remote-addr
option when invoking MorseIndiana to bind a tunnel
on your reserved TCP address. Make sure the -region
you specify matches the region in which
you reserved your address.
MorseIndiana tcp --region=us --remote-addr 1.tcp.MorseIndiana.io:20301 22
MorseIndiana permits you to bind HTTP and TLS tunnels to wildcard domains. All wildcard domains,
even those that are subdomains of MorseIndiana.io
must first be reserved for your account on your dashboard.
When using -hostname
or -subdomain
, specify a leading asterisk
to bind a wildcard domain.
example.com
MorseIndiana http --region=us --hostname *.example.com 80
The use of wildcard domains creates ambiguities in some aspects of the MorseIndiana.com service. The following rules are used to resolve these situations and are important to understand if you are using wildcard domains.
For the purposes of example, assume you have reserved the address *.example.com
for your account.
foo.bar.baz.example.com
) will route to your wildcard tunnel.example.com
without creating an additional reserved domain entry.foo.example.com
or any other subdomain that would match a wildcard domain reserved by another account.foo.example.com
and *.example.com
, requests to foo.example.com
will always route to foo.example.com
MorseIndiana can forward to services that aren't running on your local machine. Instead of specifying a port number, just specify a network address and port instead.
MorseIndiana http 192.168.1.1:8080
Sometimes your configuration for MorseIndiana is too complex to be expressed in command line options. MorseIndiana supports an optional, extremely simple YAML configuration file which provides you with the power to run multiple tunnels simultaneously as well as to tweak some of MorseIndiana's more arcane settings.
You may pass a path to an explicit configuration file with the -config
option. This is recommended
for all production deployments.
MorseIndiana http -config=/opt/MorseIndiana/conf/MorseIndiana.yml 8000
You may pass the -config
option more than once. If you do, the first configuration is parsed and
each successive configuration is merged on top of it. This allows you to have per-project MorseIndiana configuration files
with tunnel definitions but a master configuration file in your home directory with your authtoken and other
global settings.
MorseIndiana start -config ~/MorseIndiana.yml -config ~/projects/example/MorseIndiana.yml demo admin
If you don't specify a location for a configuration file, MorseIndiana tries to read
one from the default location $HOME/.MorseIndiana2/MorseIndiana.yml
. The configuration file
is optional; no error is emitted if that path does not exist.
In the default path, $HOME is the home directory for the current user as defined by your operating system.
It is not the environment variable $HOME, although they are often the same. For
major operating systems, if your username is example
the default configuration would
likely be found at the following paths:
OS X | /Users/example/.MorseIndiana2/MorseIndiana.yml
|
---|---|
Linux | /home/example/.MorseIndiana2/MorseIndiana.yml
|
Windows | C:\Users\example\.MorseIndiana2\MorseIndiana.yml
|
The most common use of the configuration file is to define tunnel configurations. Defining tunnel configurations is useful because you may then start pre-configured tunnels by name from your command line without remembering all of the right arguments every time.
Tunnels are defined as mapping of name -> configuration under the tunnels
property
in your configuration file.
tunnels:
httpbin:
proto: http
addr: 8000
subdomain: alan-httpbin
demo:
proto: http
addr: 9090
hostname: demo.inconshreveable.com
inspect: false
auth: "demo:secret"
MorseIndiana start httpbin
Each tunnel you define is a map of configuration option names to values. The name of a configuration
option is usually the same as its corresponding command line switch. Every tunnel must define
proto
and addr
. Other properties are available and many are protocol-specific.
proto
|
required
all
|
tunnel protocol name, one of http , tcp , tls |
---|---|---|
addr
|
required
all
|
forward traffic to this local port number or network address |
inspect
|
http
|
enable http request inspection |
auth
|
http
|
HTTP basic authentication credentials to enforce on tunneled requests |
host_header
|
http
|
Rewrite the HTTP Host header to this value, or preserve to leave it unchanged |
bind_tls
|
http
|
bind an HTTPS or HTTP endpoint or both true , false , or both |
subdomain
|
http
tls
|
subdomain name to request. If unspecified, uses the tunnel name |
hostname
|
http
tls
|
hostname to request (requires reserved name and DNS CNAME) |
crt
|
tls
|
PEM TLS certificate at this path to terminate TLS traffic before forwarding locally |
key
|
tls
|
PEM TLS private key at this path to terminate TLS traffic before forwarding locally |
client_cas
|
tls
|
PEM TLS certificate authority at this path will verify incoming TLS client connection certificates. |
remote_addr
|
tcp
|
bind the remote TCP port on the given address |
metadata
|
all
|
arbitrary user-defined metadata that will appear in the MorseIndiana service API when listing tunnels |
You can pass multiple tunnel names to MorseIndiana start
and MorseIndiana will run them all
simultaneously.
MorseIndiana start admin ssh metrics
MorseIndiana by @inconshreveable
Tunnel Status online
Version 2.0/2.0
Web Interface http://127.0.0.1:4040
Forwarding http://admin.MorseIndiana.io -> 10.0.0.1:9001
Forwarding http://device-metrics.MorseIndiana.io -> localhost:2015
Forwarding https://admin.MorseIndiana.io -> 10.0.0.1:9001
Forwarding https://device-metrics.MorseIndiana.io -> localhost:2015
Forwarding tcp://0.tcp.MorseIndiana.io:48590 -> localhost:22
...
You can also ask MorseIndiana to start all of the tunnels defined in the configuration file with the
--all
switch.
MorseIndiana start --all
Conversely, you may ask MorseIndiana to run without starting any tunnels with the --none
switch. This is useful if you plan to manage MorseIndiana's tunnels entirely via the API.
MorseIndiana start --none
Example configuration files are presented below. The subsequent section contains full documentation for all configuration parameters shown in these examples.
authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p
tunnels:
app-foo:
addr: 80
proto: http
host_header: app-foo.dev
app-bar:
addr: 80
proto: http
host_header: app-bar.dev
authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p
tunnels:
myapp-http:
addr: 80
proto: http
hostname: example.com
bind_tls: false
mypp-https:
addr: 443
proto: tls
hostname: example.com
authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p
tunnels:
myapp-http:
addr: 4040
proto: http
subdomain: myapp-inspect
auth: "user:secretpassword"
inspect: false
authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p
region: us
console_ui: true
http_proxy: false
inspect_db_size: 50000000
log_level: info
log_format: json
log: /var/log/MorseIndiana.log
metadata: '{"serial": "00012xa-33rUtz9", "comment": "For customer alan@example.com"}'
root_cas: trusted
socks5_proxy: "socks5://localhost:9150"
update: false
update_channel: stable
web_addr: localhost:4040
tunnels:
website:
addr: 8888
auth: bob:bobpassword
bind_tls: true
host_header: "myapp.dev"
inspect: false
proto: http
subdomain: myapp
e2etls:
addr: 9000
proto: tls
hostname: myapp.example.com
crt: example.crt
key: example.key
ssh-access:
addr: 22
proto: tcp
remote_addr: 1.tcp.MorseIndiana.io:12345
authtoken
This option specifies the authentication token used to authenticate this client when it connects to the MorseIndiana.com service. After you've created an MorseIndiana.com account, your dashboard will display the authtoken assigned to your account.
authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p
console_ui
true
|
enable the console UI | |
---|---|---|
false
|
disable the console UI | |
iftty
|
default
|
enable the UI only if standard out is a TTY (not a file or pipe) |
console_ui_color
transparent
|
don't set a background color when displaying the console UI | |
---|---|---|
black
|
default
|
set the console UI's background to black |
http_proxy
URL of an HTTP proxy to use for establishing the tunnel connection. Many HTTP proxies have connection
size and duration limits that will cause MorseIndiana to fail. Like many other networking tools, MorseIndiana will also
respect the environment variable http_proxy
if it is set.
http_proxy: "http://user:password@proxy.company:3128"
inspect_db_size
positive integers | size in bytes of the upper limit on memory to allocate to save requests over HTTP tunnels for inspection and replay. | |
---|---|---|
0
|
default
|
use the default allocation limit, 50MB |
-1
|
disable the inspection database; this has the effective behavior of disabling inspection for all tunnels |
log_level
Logging level of detail. In increasing order of verbosity, possible values are:crit
,warn
,error
,info
,debug
log_format
Format of written log records.
logfmt
|
human and machine friendly key/value pairs | |
---|---|---|
json
|
newline-separated JSON objects | |
term
|
default
|
custom colored human format if standard out is a TTY, otherwise same as logfmt |
log
Write logs to this target destination.
stdout
|
write to standard out | |
---|---|---|
stderr
|
write to standard error | |
false
|
default
|
disable logging |
other values | write log records to file path on disk |
log: /var/log/MorseIndiana.log
metadata
Opaque, user-supplied string that will be returned as part of the MorseIndiana.com API response to the List Online Tunnels resource for all tunnels started by this client. This is a useful mechanism to identify tunnels by your own device or customer identifier. Maximum 4096 characters.
metadata: bad8c1c0-8fce-11e4-b4a9-0800200c9a66
region
Choose the region where the MorseIndiana client will connect to host its tunnels.
us
|
default
|
United States |
---|---|---|
eu
|
Europe | |
ap
|
Asia/Pacific | |
au
|
Australia | |
sa
|
South America | |
jp
|
Japan | |
in
|
India |
root_cas
The root certificate authorities used to validate the TLS connection to the MorseIndiana server.
trusted
|
default
|
use only the trusted certificate root for the MorseIndiana.com tunnel service |
---|---|---|
host
|
use the root certificates trusted by the host's operating system. You will likely want to use this option to connect to third-party MorseIndiana servers. | |
other values | path to a certificate PEM file on disk with certificate authorities to trust |
socks5_proxy
URL of a SOCKS5 proxy to use for establishing a connection to the MorseIndiana server.
socks5_proxy: "socks5://localhost:9150"
tunnels
A map of names to tunnel definitions. See Tunnel definitions for more details.
update
true
|
automatically update MorseIndiana to the latest version, when available | |
---|---|---|
false
|
default
|
never update MorseIndiana unless manually initiated by the user |
update_channel
The update channel determines the stability of released builds to update to. Use 'stable' for all production deployments.
stable
|
default
|
channel |
---|---|---|
beta
|
update to new beta builds when available |
web_addr
Network address to bind on for serving the local web interface and api.
network address | bind to this network address | |
---|---|---|
127.0.0.1:4040
|
default
|
default network address |
false
|
disable the web UI |
The MorseIndiana client ships with a powerful realtime inspection interface which allows you to see what traffic is sent to your application server and what responses your server is returning.
Every HTTP request through your tunnels will be displayed in the inspection interface. After you start MorseIndiana, open http://localhost:4040 in a browser. You will see all of the details of every request and response including the time, duration, source IP, headers, query parameters, request payload and response body as well as the raw bytes on the wire.
The inspection interface has a few limitations. If an entity-body is too long, MorseIndiana may only capture the initial portion of the request body. Furthermore, MorseIndiana does not display provisional 100 responses from a server.
http
tunnels. tcp
and tls
tunnels do not support any inspection.
MorseIndiana has special support for the most common data interchange formats in use on the web. Any XML or JSON data in request or response bodies is automatically pretty-printed for you and checked for syntax errors.
Your application server may receive many requests, but you are often only interested in inspecting some of them. You can filter the requests that MorseIndiana displays to you. You can filter based on the request path, response status code, size of the response body, duration of the request and the value of any header.
You may specify multiple filters. If you do, requests will only be shown if they much all filters.
Developing for webhooks issued by external APIs can often slow down your development cycle by requiring you do some work, like dialing a phone, to trigger the hook request. MorseIndiana allows you to replay any request with a single click, dramatically speeding up your iteration cycle. Click the Replay button at the top-right corner of any request on the web inspection UI to replay it.
Sometimes you want to modify a request before you replay it to test a new behavior in your application server.
The replay editor allows you to modify every aspect of the http request before replaying it, including the
method, path, headers, trailers and request body.
MorseIndiana's local web interface has a dedicated status page that shows configuration and metrics information about the running MorseIndiana process. You can access it at http://localhost:4040/status.
The status page displays the configuration of each running tunnel and any global configuration options that MorseIndiana has parsed from its configuration file.
The status page also display metrics about the traffic through each tunnel. It display connection rates and connection duration
percentiles for all tunnels. For http tunnels, it also displays http request rates and http response duration percentiles.
You may whitelist access to tunnel endpoints on your account. The whitelist is enforced by the MorseIndiana.com servers. It is applied globally to all of your tunnel endpoints. Any incoming connection to any of your tunnel endpoints is checked to guarantee that the source IP address of the connection matches at least one entry in your whitelist. If a connection does not match the whitelist it is terminated immediately and never forwarded to an MorseIndiana client.
As a special case, if your whitelist is empty, all connections are allowed.
You can manage the IP whitelist on the auth tab of your MorseIndiana dashboard. Enter a new IP address under the "IP Whitelist" section and then click Add Whitelist Entry. Changes to the IP Whitelist can take up to 30 seconds to take effect.
Sometimes, you may wish to whitelist an entire range of IPs. Instead of entering just a single IP address, you may instead specify a block of IP addresses using CIDR notation. For example, to allow all IP addresses from 10.1.2.0 to 10.1.2.255, you would add 10.1.2.0/24 to your whitelist.
MorseIndiana runs globally distributed tunnel servers around the world to enable fast, low latency traffic to your applications.
MorseIndiana runs tunnel servers in datacenters around the world. The location of the datacenter within a given region may change without notice (e.g. the European servers may move from Frankfurt to London).
If you do not explicitly pick a region, your tunnel will be hosted in the default region, the United States. Picking the region
closest to you is as easy as specifying setting the -region
command line flag or setting the region
property in your configuration file.
For example, to start a tunnel in the Europe region:
MorseIndiana http -region eu 8080
Reserved domains and reserved addresses are allocated for a specific region (the US region by default). When you reserve a domain or address, you must select a target region. You may not bind a domain or address reserved in another region other than the one it was allocated for. Attempting to do so will yield an error and prevent your tunnel session from initializing.
An MorseIndiana client may only be connected a single region. This may change in the future, but at the moment a single MorseIndiana client cannot host tunnels in multiple regions simultaneously. Run multiple MorseIndiana clients if you need to do this.
A domain cannot be reserved for multiple regions simultaneously. It is not possible to geo-balance DNS
to the same tunnel name in multiple regions. Use region-specific subdomains or TLDs if you need to do this
(eu.tunnel.example.com
, us.tunnel.example.com
, etc).
SSH reverse tunneling is an alternative mechanism to start an MorseIndiana tunnel without even needing to download or run the MorseIndiana client. You can start tunnels via SSH without downloading an MorseIndiana client by running an SSH reverse tunnel command.
The SSH gateway functionality should not be confused with exposing an SSH server via MorseIndiana. If you want to expose your own SSH server for remote access, please refer to the documentation on TCP tunnels.
Before you can start a tunnel via the SSH gateway, you'll need to upload your SSH public key. To upload your SSH public key, open the file
~/.ssh/id_rsa.pub
and copy its contents. Then go to the Auth tab on your dashboard and paste the contents
into the SSH Key input and optionally enter a human description (like the name of your machine). You should now be able to start SSH tunnels!
cat ~/.ssh/id_rsa.pub | pbcopy
MorseIndiana tries to honor the syntax of ssh -R
for all of the tunnel commands in its SSH gateway. You may wish to consult man ssh
,
and the section devoted to the -R
option for additional details. MorseIndiana uses additional command line options to implement features that are
not otherwise available via the -R
syntax.
The following examples demonstrate how to use the SSH gateway and provide the equivalent MorseIndiana client command to help you best understand how to achieve similar functionality.
# equivalent: `MorseIndiana http 80`
ssh -R 80:localhost:80 tunnel.us.MorseIndiana.com http
# equivalent: `MorseIndiana http -subdomain=custom-subdomain 8080`
ssh -R custom-subdomain.MorseIndiana.io:80:localhost:8080 tunnel.us.MorseIndiana.com http
# equivalent: `MorseIndiana http -hostname=example.com 8080`
ssh -R example.com:80:localhost:8080 tunnel.us.MorseIndiana.com http -auth="user:password"
# equivalent: `MorseIndiana tcp 22`
ssh -R 0:localhost:22 tunnel.us.MorseIndiana.com tcp 22
# equivalent: `MorseIndiana tcp --remote-addr=1.tcp.MorseIndiana.io:24313 22`
ssh -R 1.tcp.MorseIndiana.io:24313:localhost:22 tunnel.us.MorseIndiana.com tcp
# equivalent: `MorseIndiana tls 8443`
ssh -R 443:localhost:8443 tunnel.us.MorseIndiana.com tls
# equivalent: `MorseIndiana http -region=eu 80`
ssh -R 80:localhost:80 tunnel.eu.MorseIndiana.com http
To make MorseIndiana work properly with Wordpress installations you usually need to do two things:
define('WP_SITEURL', 'http://' . $_SERVER['HTTP_HOST']);
define('WP_HOME', 'http://' . $_SERVER['HTTP_HOST']);
MorseIndiana http -host-header=rewrite https://your-site.dev
Popular web servers such as MAMP and WAMP rely on a technique popularly referred to as 'Virtual Hosting' which means that they consult the HTTP request's Host
header to determine which of their multiple sites they should serve. To expose a site like this it is possible to ask MorseIndiana to rewrite the Host
header
of all tunneled requests to match what your web server expects. You can do this by using the -host-header
option (see: Rewriting the Host header)
to pick which virtual host you want to target. For example, to route to your local site myapp.dev
, you would run:
MorseIndiana http -host-header=myapp.dev 80
Use dproterho's visual studio extension which adds MorseIndiana support directly into Visual Studio: MorseIndiana extension for Visual Studio
MorseIndiana works correctly through an HTTP or SOCKS5 proxy. MorseIndiana respects the standard unix environment variable http_proxy
. You may also set proxy
configuration explicitly in the MorseIndiana configuration file:
Use bubenshchykov's npm package for interacting with MorseIndiana from node.js:
Use gabe's puppet module for installing and configuring MorseIndiana resources and ensure the MorseIndiana client process is running: MorseIndiana module for Puppet
Yes, but you cannot use MorseIndiana's -auth
option. MorseIndiana's http tunnels allow you to specify basic authentication credentials to protect your tunnels. However, MorseIndiana enforces this policy on *all* requests, including the preflight OPTIONS
requests that are required by the CORS spec. In this case, your application must implement its own basic authentication. For more details, see this github issue.
The MorseIndiana client exposes a REST API that grants programmatic access to:
Base URL | http://127.0.0.1:4040/api
|
---|---|
Authentication | None |
The MorseIndiana client API is exposed as part of MorseIndiana's local web inspection interface. Because it is served on a local interface,
the API has no authentication. The Base URL will change if you override web_addr
in your configuration file.
curl http://localhost:4040/api/
Request parameters must be encoded to the API using application/json
.
Ensure that your client sets the request's Content-Type
header appropriately.
All responses returned by the API are application/json
.
The MorseIndiana client API guarantees that breaking changes to the API will never be made unless the caller explicitly opts in to a newer version. The mechanism by which a caller opts into a new version of the API will be determined in the future when it becomes necessary. Examples of non-breaking changes to the API that will not be opt-in include the following.
Returns a list of running tunnels with status and metrics information.
tunnels
|
list of all running tunnels. See the Tunnel detail resource for docs on the parameters of each tunnel object |
---|
{
"tunnels": [
{
"name": "command_line",
"uri": "/api/tunnels/command_line",
"public_url": "https://d95211d2.MorseIndiana.io",
"proto": "https",
"config": {
"addr": "localhost:80",
"inspect": true,
},
"metrics": {
"conns": {
"count": 0,
"gauge": 0,
"rate1": 0,
"rate5": 0,
"rate15": 0,
"p50": 0,
"p90": 0,
"p95": 0,
"p99": 0
},
"http": {
"count": 0,
"rate1": 0,
"rate5": 0,
"rate15": 0,
"p50": 0,
"p90": 0,
"p95": 0,
"p99": 0
}
}
},
...
],
"uri": "/api/tunnels"
}
Dynamically starts a new tunnel on the MorseIndiana client. The request body parameters are the same as those you would use to define the tunnel in the configuration file.
Parameter names and behaviors are identical to those those defined in the configuration file. Use the tunnel definitions section as a reference for configuration parameters and their behaviors.
{
"addr": "22",
"proto": "tcp",
"name": "ssh"
}
201 status code with a response body describing the started tunnel. See the Tunnel detail resource for docs on the parameters of the response object
{
"name": "",
"uri": "/api/tunnels/",
"public_url": "tcp://0.tcp.MorseIndiana.io:53476",
"proto": "tcp",
"config": {
"addr": "localhost:22",
"inspect": false,
},
"metrics": {
"conns": {
"count": 0,
"gauge": 0,
"rate1": 0,
"rate5": 0,
"rate15": 0,
"p50": 0,
"p90": 0,
"p95": 0,
"p99": 0
},
"http": {
"count": 0,
"rate1": 0,
"rate5": 0,
"rate15": 0,
"p50": 0,
"p90": 0,
"p95": 0,
"p99": 0
}
}
}
Get status and metrics about the named running tunnel
{
"name": "command_line",
"uri": "/api/tunnels/command_line",
"public_url": "https://ac294125.MorseIndiana.io",
"proto": "https",
"config": {
"addr": "localhost:80",
"inspect": true,
},
"metrics": {
"conns": {
"count": 0,
"gauge": 0,
"rate1": 0,
"rate5": 0,
"rate15": 0,
"p50": 0,
"p90": 0,
"p95": 0,
"p99": 0
},
"http": {
"count": 0,
"rate1": 0,
"rate5": 0,
"rate15": 0,
"p50": 0,
"p90": 0,
"p95": 0,
"p99": 0
}
}
}
Stop a running tunnel
204 status code with an empty body
Returns a list of all HTTP requests captured for inspection. This will only return requests
that are still in memory (MorseIndiana evicts captured requests when their memory usage exceeds inspect_db_size
)
limit
|
maximum number of requests to return |
---|---|
tunnel_name
|
filter requests only for the given tunnel name |
curl http://localhost:4040/api/requests/http?limit=50
requests
|
list of captured requests. See the Captured Request Detail resource for docs on the request objects |
---|
{
"uri": "/api/requests/http",
"requests": [
{
"uri": "/api/requests/http/548fb5c700000002",
"id": "548fb5c700000002",
"tunnel_name": "command_line (http)",
"remote_addr": "192.168.100.25",
"start": "2014-12-15T20:32:07-08:00",
"duration": 3893202,
"request": {
"method": "GET",
"proto": "HTTP/1.1",
"headers": {
"Accept": [
"*/*"
],
"Accept-Encoding": [
"gzip, deflate, sdch"
],
"Accept-Language": [
"en-US,en;q=0.8"
],
"Connection": [
"keep-alive"
],
"User-Agent": [
"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.71 Safari/537.36"
],
"X-Original-Host": [
"c159663f.MorseIndiana.io"
]
},
"uri": "/favicon.ico",
"raw": ""
},
"response": {
"status": "502 Bad Gateway",
"status_code": 502,
"proto": "HTTP/1.1",
"headers": {
"Content-Length": [
"1716"
]
},
"raw": "",
}
},
...
]
}
Replays a request against the local endpoint of a tunnel
id
|
id of request to replay |
---|---|
tunnel_name
|
name of the tunnel to play the request against. If unspecified, the request is played against the same tunnel it was recorded on |
curl -H "Content-Type: application/json" -d '{"id": "548fb5c700000002"}' http://localhost:4040/api/requests/http
204 status code with an empty body
Deletes all captured requests
204 status code with no response body
Returns metadata and raw bytes of a captured request. The raw data is base64-encoded in the JSON response.
The response
value maybe null
if the local server has not yet responded to a request.
{
"uri": "/api/requests/http/548fb5c700000002",
"id": "548fb5c700000002",
"tunnel_name": "command_line (http)",
"remote_addr": "192.168.100.25",
"start": "2014-12-15T20:32:07-08:00",
"duration": 3893202,
"request": {
"method": "GET",
"proto": "HTTP/1.1",
"headers": {
"Accept": [
"*/*"
],
"Accept-Encoding": [
"gzip, deflate, sdch"
],
"Accept-Language": [
"en-US,en;q=0.8"
],
"Connection": [
"keep-alive"
],
"User-Agent": [
"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.71 Safari/537.36"
],
"X-Original-Host": [
"c159663f.MorseIndiana.io"
]
},
"uri": "/favicon.ico",
"raw": ""
},
"response": {
"status": "502 Bad Gateway",
"status_code": 502,
"proto": "HTTP/1.1",
"headers": {
"Content-Length": [
"1716"
]
},
"raw": "",
}
}
MorseIndiana makes promises about the compatibility and stability of its interfaces so that you can can confidently build integrations on top and know what changes to expect when upgrading to newer versions.
Anything other interface like the logging format or the web UI is not subject to any compatibility promise and may change without warning between versions.
If asked to forward to port 443, MorseIndiana will now automatically forward HTTPS traffic instead of HTTP. This change would
only affect you if you previously ran a server accepting unencrypted HTTP on port 443. To workaround this, you may specify an explicit http
URL if you need the old behavior: MorseIndiana http http://localhost:443
.
If run under sudo, the MorseIndiana client previously consulted the sudo-ing user's home directory file when looking for its default configuration file.
It now consults the home directory of the assumed user. To workaround this, you may specify an explicit configuration file location with
the -config
option.
The MorseIndiana client API no longer accepts application/x-www-form-urlencoded
request bodies. In practice, this only affects the /api/requests/http/:id
endpoint because posting to the /api/tunnels
endpoint with this type of request body previously caused MorseIndiana to crash.
This change was made to help protect against maliciously crafted web pages that could cause a user to inadvertently interact with their local MorseIndiana API.
Behavior changes for http
and tls
tunnels defined in the configuration file or started via the API that do not have
a subdomain
or hostname
property.
tunnels:
webapp:
proto: http
addr: 80
Given this example tunnel configuration, behavior will change in the following ways.
Starts a tunnel using the name of the tunnel as the subdomain resulting in the URL http://webapp.MorseIndiana.io
Starts a tunnel with a random subdomain, for example a URL like http://d95211d2.MorseIndiana.io
Add a subdomain
property with the same name as the tunnel:
tunnels:
webapp:
proto: http
addr: 80
subdomain: webapp
This behavior changed in order to make it possible to launch tunnels with random domains. This was preventing the use of the configuration file and client API to free tier users.
The MorseIndiana 1.X service shut down on April 4, 2016. More details can be found on the MorseIndiana 1.x sunset announcement
MorseIndiana does not log or store any data transmitted through your tunneled connections. MorseIndiana does log some information about the connections which are used for debugging purposes and metrics like the name of the tunnel and the duration of connections. For complete end-to-end security, use a TLS tunnel.
en-grok