icflorescu / iisexpress-proxy

A simple local proxy for accessing IIS Express from remote machines.

iisexpress-proxy

A simple, yet practical command-line utility enabling .NET developers to test web applications served by IIS Express on remote devices.

Motivation

Are you a .NET developer building mobile web applications? Have you ever been frustrated by the fact that there's no easy way to enable IIS Express to accept connections from remote devices?...

Installation

There's no need to install iisexpress-proxy if you're using npm@^5.2.0; you can simply run it with npx. If you're using an older version of npm, you'll most likely want iisexpress-proxy installed as a global module:

npm install -g iisexpress-proxy

Note: You need to have Node.js installed.

Usage

If you're using npm@^5.2.0:

npx iisexpress-proxy localPort to proxyPort

Alternatively, if you installed iisexpress-proxy as a global npm module:

iisexpress-proxy localPort to proxyPort

For instance, if your application's IIS Express port is 51123, run this in the Command Prompt:

iisexpress-proxy 51123 to 3000

The program will list the external addresses you can use for testing your application on remote devices.

iisexpress-proxy defaults to http, so if your application is running https, then include the full URL.

iisexpress-proxy https://localhost:51123 to 3000

Note that this will terminate HTTPS. On your destination machine, connect to port 3000 using HTTP, not HTTPS.

If you want the proxy itself to serve HTTPS, you can specify the target with the full URL as well.

iisexpress-proxy https://localhost:51123 to https://*:3000

This will generate a self-signed certificate and use it, openssl must be in PATH for this to work.

If you're on Windows, the easiest way to get openssl is to use Git Bash that comes with it pre-installed.

If you want to bind to a specific interface instead of all of them, use its IP in the target URL, e.g. https://10.0.0.1:3000. Note that the right-hand part cannot be a domain name.

Advanced usage (VPN, virtual hosts, etc.)

You can also use iisexpress-proxy to expose an IIS server instance running on a different host accessible through VPN, like this:

iisexpress-proxy host:port to proxyHost:proxyPort

For instance, let's conside this scenario:

• the application is running on 192.168.96.3:5000 and it only accepts connections from clients within a VPN;
• your development machine has a network interface within the same VPN and another publicly accessible one (192.168.0.102);
• you need to test the application from mobile devices without having to add those devices to the VPN.

By running this in the Command Prompt:

iisexpress-proxy 192.168.96.3:5000 to 192.168.0.102:3000

...you'll be able to access the application by pointing the mobile devices to 192.168.0.102:3000.

For another advanced example, consider that you're on public Wifi and don't want to publicly expose your dev server. You could set up a VPN between your laptop and your phone and only expose the server on the VPN interface (10.0.0.1). Then you can run

iisexpress-proxy 5000 to 10.0.0.1:8080

...and open http://10.0.0.1:8080 on your phone with VPN enabled, while other wifi users won't be able to connect.

Note: This functionality was added at v1.1.0 (released 10/21/2015).

WebSocket support was added in v1.4.0 by Stan Hebben - see PR #11 for details.

If you don't want using generated certificates you could provide your own certificate and key using cert/key arguments:

iisexpress-proxy https://localhost:51123 to https://*:3000 --key=./your-key.pem --cert=./your-cert.pem

Note: This functionality was added at v1.7.0 (released 02/14/2022).

Limitations

iisexpress-proxy doesn't work in scenarios involving integrated Windows authentication (see issue #here).

How does it work

It's proxying the HTTP traffic on localPort to proxyPort on all the available network interfaces and it's also changing the origin of the host header, allowing you to test web applications hosted by IIS Express on various remote devices (mobile devices, other desktops, etc.).

If you need to access the original host requested by the browser, the request headers will include X-Forward headers. In ASP.NET, Request.Headers["x-forwarded-host"] will contain the requested host.

Credits and attributions

This command-line utility wraps http-proxy. The original http-proxy logo was created by Diego Pasquali.

Contributors

Endorsing the author

If you find this repo useful, please give it a star, tweet about it and endorse me on LinkedIn:

Before raising issues

I'm getting lots of questions from people just learning to do web development or simply looking to solve a very specific problem they're dealing with. While I will answer some of them for the benefit of the community, please understand that open-source is a shared effort and it's definitely not about piggybacking on other people's work. On places like GitHub, that means raising issues is encouraged, but coming up with useful PRs is a lot better. If I'm willing to share some of my code for free, I'm doing it for a number of reasons: my own intellectual challenges, pride, arrogance, stubbornness to believe I'm bringing a contribution to common progress and freedom, etc. Your particular well-being is probably not one of those reasons. I'm not in the business of providing free consultancy, so if you need my help to solve your specific problem, there's a fee for that.

❤️🇺🇦

On 24th of February 2022 Russia unlawfully invaded Ukraine. This is an unjustified, unprovoked attack on the sovereignty of a neighboring country, but also an open affront to international peace and stability that has the potential to degenerate into a nuclear event threatening the very existence of humanity. I am a Romanian (EU) citizen, but I stand with Ukraine and I am doing everything in my power to stop this madness. Here's how you can show your support.

License

The ISC License.

iisexpress-proxy's Issues

To all contributors - notice to show support for UA

To all contributors: I've added a README support notice against Russia's unlawful invasion of Ukraine. Hope you won't mind.

Error: connect ECONNREFUSED

Version 1.0.1

Crash when request to 10.211.55.3:4000 on Windows 10.

C:\Users\wk>iisexpress-proxy 25840 to 4000
IIS Express Proxy 1.0.1
Proxying localhost:25840 to:
- Ethernet: 10.211.55.3:4000
Listening... [ press Control-C to exit ]
C:\Users\wk\AppData\Roaming\npm\node_modules\iisexpress-proxy\node_modules\http-proxy\lib\http-proxy\index.js:119
    throw err;
          ^
Error: connect ECONNREFUSED
    at exports._errnoException (util.js:746:11)
    at TCPConnectWrap.afterConnect [as oncomplete] (net.js:1010:19)

Request requires localhost

Hi, the proxy forwards to 127.0.0.1 which results in a refused connection. I only seem to be able to request successfully from localhost. Why might this be?

Offline installation fails - npmbox npmunbox

I receive the following trying to install to a system with no internet connection.:
c:>npmunbox -v -g iisexpress-proxy.npmbox

Unboxing iisexpress-proxy.npmbox...
Unpacking iisexpress-proxy.npmbox...
Installing iisexpress-proxy...
npm verb request uri https://registry.npmjs.org/iisexpress-proxy
npm verb request no auth needed
npm info attempt registry request try #1 at 11:53:50 AM
npm verb request id e98fff2ab2b30d40
npm http request GET https://registry.npmjs.org/iisexpress-proxy
An error occurred while installing iisexpress-proxy.
iisexpress-proxy was not installed.
{ [Error: connect ETIMEDOUT 151.101.44.162:443]
code: 'ETIMEDOUT',
errno: 'ETIMEDOUT',
syscall: 'connect',
address: '151.101.44.162',
port: 443 }
Done.

Cannot access RESTful URLs which are returning UTF8+BOM encoded JSON

Hi,

it seems that the proxy is trying to parse JSON that is going through it. I can access static pages via the proxy without any problems, but when I am trying to access any restful services, then it fails with the following error:

Error: Parse Error
    at Error (native)
    at Socket.socketOnData (_http_client.js:309:20)
    at emitOne (events.js:77:13)
    at Socket.emit (events.js:169:7)
    at readableAddChunk (_stream_readable.js:153:18)
    at Socket.Readable.push (_stream_readable.js:111:10)
    at TCP.onread (net.js:531:20)

If more information is needed, please let me know.

Thanks,
Ignas

Great utility

However, you would earn greater respect from a far greater percentage of developers if you were to leave your anti Russian political diatribe out of GitHub !

Error: Can't set headers after they are sent.

iisexpress-proxy 2097 to 5000
Listening... [press Control-C to exit]
_http_outgoing.js:356
throw new Error('Can't set headers after they are sent.');
^

Error: Can't set headers after they are sent.
at ServerResponse.OutgoingMessage.setHeader (_http_outgoing.js:356:11)
at ServerResponse.writeHead (_http_server.js:180:21)
at ProxyServer. (C:\Users\javier\AppData\Roaming\npm\node_modules\iisexpress-proxy\index.js:64:7)
at ProxyServer.emit (C:\Users\javier\AppData\Roaming\npm\node_modules\iisexpress-proxy\node_modules\eventemitter3\index.js:144:27)
at ClientRequest.proxyError (C:\Users\javier\AppData\Roaming\npm\node_modules\iisexpress-proxy\node_modules\http-proxy\lib\http-proxy\passes\web-incoming.js:156:18)
at emitOne (events.js:96:13)
at ClientRequest.emit (events.js:188:7)
at Socket.socketErrorListener (_http_client.js:310:9)
at emitOne (events.js:96:13)
at Socket.emit (events.js:188:7)

AWS EC2

This works beautifully on my dev laptop, thanks, but how to use it on a Win Server 2016 EC2 instance?

It sees the private IP address, but I need it to listen to the public IP address.

So something like iisexpress-proxy 51123 to publicip:3000

Inside the instance, ipconfig does not show the public ip address.

Please mention in the read-me that projects with integrated Windows authentication aren't supported

First things first: thanks for a great utility.

It seems that projects that use integrated Windows authentication aren't supported by iisexpress-proxy - I get a "401.2 Unauthorized" error complaining about "invalid authentication headers".

Not sure if supporting such projects is even an option or on your roadmap, but it would be helpful if you documented the limitation in README.md.

Url not matching regex

After I have installed iis-express following error is thrown:

iisexpress-proxy https://localhost:44355/ to 3000
IIS Express Proxy 1.7.3
C:\Users{username}\AppData\Roaming\npm\node_modules\iisexpress-proxy\index.js:39
var targetMatch = args._[4].match(urlRegExp);
^

TypeError: args._[4].match is not a function
at Object. (C:\Users{username}\AppData\Roaming\npm\node_modules\iisexpress-proxy\index.js:39:29)
at Module._compile (internal/modules/cjs/loader.js:1063:30)
at Object.Module._extensions..js (internal/modules/cjs/loader.js:1092:10)
at Module.load (internal/modules/cjs/loader.js:928:32)
at Function.Module._load (internal/modules/cjs/loader.js:769:14)
at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:72:12)
at internal/main/run_main_module.js:17:47

Url not matching regex ^2

In addition to #35 - maybe same thing missing here:

const sourceMatch = args._[2].match(urlRegExp);

so perhaps?

const sourceMatch = String(args._[2]).match(urlRegExp);

Because IIS Express Proxy 1.7.4 is giving me
args._[2].match is not a function

: Awesome work.
signed.

permissions denied

I'm getting this error (windows 10):

C:\WINDOWS\system32>iisexpress-proxy 5003 to 8099
IIS Express Proxy 1.4.9
Proxying http://localhost:5003 to network interfaces:
VMware Network Adapter VMnet1: 192.168.88.1:8099
VMware Network Adapter VMnet8: 192.168.60.1:8099
Wi-Fi: 192.168.178.20:8099
vEthernet (Default Switch): 172.17.216.49:8099
Error: listen EACCES: permission denied 0.0.0.0:8099
at Server.setupListenHandle [as _listen2] (net.js:1262:19)
at listenInCluster (net.js:1327:12)
at Server.listen (net.js:1414:7)
at Object. (C:\Users\ronta\AppData\Roaming\npm\node_modules\iisexpress-proxy\index.js:72:13)
at Module._compile (internal/modules/cjs/loader.js:778:30)
at Object.Module._extensions..js (internal/modules/cjs/loader.js:789:10)
at Module.load (internal/modules/cjs/loader.js:653:32)
at tryModuleLoad (internal/modules/cjs/loader.js:593:12)
at Function.Module._load (internal/modules/cjs/loader.js:585:3)
at Function.Module.runMain (internal/modules/cjs/loader.js:831:12)
Listening... [press Control-C to exit]
C:\Users...\AppData\Roaming\npm\node_modules\iisexpress-proxy\index.js:77
res.writeHead(500, {
^

TypeError: Cannot read property 'writeHead' of undefined
at Server. (C:\Users...\AppData\Roaming\npm\node_modules\iisexpress-proxy\index.js:77:7)
at Server.emit (events.js:198:13)
at emitErrorNT (net.js:1306:8)
at process._tickCallback (internal/process/next_tick.js:63:19)
at Function.Module.runMain (internal/modules/cjs/loader.js:834:11)
at startup (internal/bootstrap/node.js:283:19)
at bootstrapNodeJSCore (internal/bootstrap/node.js:622:3)

Tried also using console with admin rights

Replace repo logo

Replace repo logo with something like this...

Using IIS Express with Internet Connection Sharing

Hi,

Unfortunately, I am obliged to use ICS to share my internet connection.

With ICS enabled, I am unable to run IIS Express - I get this error:

"c:\Program Files\IIS Express\iisexpress" /port:63293 /path:"C:\Visual Studio Projects\Cornhouse.PepperFactory\Cornhouse.PepperFactory.UI"
Copied template config file 'c:\Program Files\IIS Express\AppServer\applicationhost.config' to 'D:\Temp\iisexpress\applicationhost2016423131125484.config'
Updated configuration file 'D:\Temp\iisexpress\applicationhost2016423131125484.config' with given cmd line info.
Starting IIS Express ...
Failed to register URL "http://localhost:63293/" for site "Development Web Site" application "/". Error description: Access is denied. (0x80070005)
Registration completed
Unable to start iisexpress.

Access is denied.
For more information about the error, run iisexpress.exe with the tracing switch enabled (/trace:error).

Is there any way that iisexpress-proxy can help me with this?

My knowldege of networking is about zilch!

Many thanks
Jeremy

Support a range of ports?

First of all thanks for this great little tool! Would it be possible to support a range of ports? I have multiple sites running on different ports (like port 8100 to port 8105). It would be great if we could specify a range of ports to be proxied, so for example that the port s 8100 to 8105 would be mapped to a range from 3001 to 3005. This way it would not be necessary to start iisexpress-proxy multiple times for each site.

localhost subdomain

Hello,

I have multiple websites served from my asp.net core mvc app.

specifically, ct-1.localhost and ct-2.localhost.

this is the command line i tried:
npx iisexpress-proxy http://ct-1.localhost:62114 to 3000

and this is the response upon requesting it externally:

PS C:\Users\xxx> npx iisexpress-proxy ct-1.localhost:62114 to 3000
{
  _: [
    'C:\\Program Files\\nodejs\\node.exe',
    'C:\\Users\\xxxx\\AppData\\Roaming\\npm\\node_modules\\iisexpress-proxy\\index.js',
    'ct-1.localhost:62114',
    'to',
    3000
  ]
}
IIS Express Proxy 1.7.13
Proxying http://ct-1.localhost:62114 to network interfaces:
        Ethernet: http://192.168.1.171:3000
        Ethernet 2: http://192.168.56.1:3000
Listening... [press Control-C to exit]
Error: getaddrinfo ENOTFOUND ct-1.localhost
    at GetAddrInfoReqWrap.onlookupall [as oncomplete] (node:dns:118:26) {
  errno: -3008,
  code: 'ENOTFOUND',
  syscall: 'getaddrinfo',
  hostname: 'ct-1.localhost'
}
^C^CTerminate batch job (Y/N)? y

if I serve 62114 to 3000 my web portal shows, and displays my default behavior of showing me links to ct-1.localhost and ct-2.localhost, so the website is working correctly at bare minimum.

I have also tried ct-1.desktop-name:3000 and the browser returns IP not found.

I have used your tool many times for other web apps, and I am very happy it has worked so well!

This is just a out-of-the-norm use-case. Any help is appreciated, Thanks!

Not working on windows 11 on MacBook Pro M1 via Parallels Desktop

I used windows 11 on MacBook Pro M1 via Parallels Desktop. When I tried this package it doesn’t work.

Dynamically generated absolute URLs are broken

I have a method in my web app that builds absolute URLs (for assets). Using this proxy causes all links generated by this method to fail (links are referencing the old localhost url instead of the one in the browser). This would be great otherwise.

        public static string BuildAbsoluteURL(string virtualPath)
        {
            bool https = HttpContext.Current.Request.IsSecureConnection;
            if (!https)
            {
                var xproto = HttpContext.Current.Request.Headers["X-FORWARDED-PROTO"];
                if (xproto != null && xproto.ToLower() == "https")
                    https = true;
            }
            var absolutePathTarget = new Uri("http://" + HttpContext.Current.Request.Url.Authority + HttpContext.Current.Request.ApplicationPath.TrimEnd('/') + VirtualPathUtility.ToAbsolute(virtualPath, System.Web.HttpContext.Current.Request.ApplicationPath));
            var url = absolutePathTarget.ToString();
            if (https)
                url = "https://" + url.Substring("http://".Length);
            return url;
        }

SSL Support

Hi! Been using it successfully for a while. What about sites running on SSL? Is it possible to bridge those?

HTTPS

Hi !

How can i make this working with https url ?

Thanks

SignalR not working with proxy.

WebSocket connection to 'ws://guest:5000/signalr/connect?transport=webSockets&clientProtocol=1.5&connectionToken=2sHfR1yy9nfjoohNtgQy2uUIFHvIsSkKJMf5vBWPwUhm4yFGjvmrfwoFV%2BME5LjVCY7JziJjNjneWF3Z3QyLyIY6tSeCwhtgxE%2FeiInNhgB8%2BSVzRPsEQE4xa6SE%2Fo8ipbs9cyXiDI6R7%2BpbNBXYXTE1%2BGZOqaZrfFHPBVW7YhI%3D&connectionData=%5B%7B%22name%22%3A%22scannerhub%22%7D%5D&tid=5' failed: Connection closed before receiving a handshake response

This is the error I receive in a page that have SignalR client. Probably it is not supporting web sockets.

Swagger doesn't work properly with the plugin

The "forwarding" works just fine, but in case of usage with Swagger - swagger has issues connecting. Usually returns

{
  "error": "no response from server"
}

in case of Json
Despite that, if you call the methods via postman, on the external IP, it works just fine.

Redirects to the IIS server should be transformed

When the IIS express server does a redirect (status 301, 302, 303, 307, 308), the same port-redirection should be applied.

For example, I started the proxy with iisexpress-proxy 53856 to 8079. When IIS express then sends a location:http://localhost:53856/login/ header, it should be rewritten to location:http://<request-host>:8079/login/, because the original URL will by definition not work.

unable to use it on android emulator like gennymotion

Microsoft Windows [Version 10.0.14393]
(c) 2016 Microsoft Corporation. All rights reserved.
C:\Users\SHILPA>iisexpress-proxy 54704 to 54300
IIS Express Proxy 1.3.0
Proxying http://localhost:54704 to network interfaces:
VirtualBox Host-Only Network: 192.168.141.2:54300
Ethernet: 192.168.93.1:54300
Ethernet 2: 192.168.193.1:54300
Wireless Network Connection: 192.168.0.2:54300
Listening... [press Control-C to exit]
^CTerminate batch job (Y/N)? y

Sorry for not being active during the last couple of weeks

Sorry for being inactive lately, but over the last couple of weeks, we've had a busy schedule in Bucharest protesting against corruption in government and public administration.

Thank you for understanding. I'll get back to maintaining the repo as soon as we're done here.

Doesn't work with HTTPS

Dear developer,

I have a.NET app, which works only in localhost, because if I am trying to connect to it remotely I get a Bad Request error. I am trying to redirect localhost port to my public interface:

C:\Users\a>iisexpress-proxy https://localhost:41959 to 41000
IIS Express Proxy 1.1.8
Proxying https://localhost:41959 to network interfaces:
Local Area Connection: 192.168.1.10:41000
Listening... [press Control-C to exit]

...and the result is:

https://192.168.1.10:41959: can't open the page

a$ curl https://192.168.1.10:3000 -v

• Rebuilt URL to: https://192.168.1.10:3000/
• Trying 192.168.1.10...
• Connected to 192.168.1.10 (192.168.1.10) port 3000 (#0)
• WARNING: using IP address, SNI is being disabled by the OS.
• Server aborted the SSL handshake
• Closing connection 0
  curl: (35) Server aborted the SSL handshake

http://192.168.1.10:41959:

Aw snap! Something went wrong. Check your console to see the error.

Log:
Error: unable to verify the first certificate
at Error (native)
at TLSSocket. (_tls_wrap.js:1060:38)
at emitNone (events.js:86:13)
at TLSSocket.emit (events.js:185:7)
at TLSSocket._finishInit (_tls_wrap.js:584:8)
at TLSWrap.ssl.onhandshakedone (_tls_wrap.js:416:38)
Listening... [press Control-C to exit]

I think because we redirect https to http. Is there any way to keep the https connection? My app can listen on https only.

Something like this:

C:\Users\a>iisexpress-proxy https://localhost:41959 to https://:41000

Regards,
Adrian

Problematic dependency on OpenSSL

I tried to run iisexpress-proxy, both using npx and installing it globally via npm. In both cases, it errored because it couldn't find the openssl command. This is confusing, because there is no mention of openssl in the README dependencies, and yet it seems like a must-have for this to work. In any case, I downloaded openssl and then added it to my PATH variable, then had to manually create a openssl.cnf file and add that to my environment variables as OPENSSL_CONF.

Finally then did the iisexpress-proxy command run, however now it's erroring about a key being too small.

PS C:\Users\justintoth> iisexpress-proxy https://localhost:44359 to https://auth-dev.mydomain:443
IIS Express Proxy 1.6.0
Proxying https://localhost:44359 to network interfaces:
node:internal/tls/secure-context:65
    context.setCert(cert);
            ^

Error: error:140AB18F:SSL routines:SSL_CTX_use_certificate:ee key too small
    at node:internal/tls/secure-context:65:13
    at Array.forEach (<anonymous>)
    at setCerts (node:internal/tls/secure-context:63:3)
    at configSecureContext (node:internal/tls/secure-context:152:5)
    at Object.createSecureContext (node:_tls_common:116:3)
    at Server.setSecureContext (node:_tls_wrap:1344:27)
    at Server (node:_tls_wrap:1203:8)
    at new Server (node:https:69:3)
    at Object.createServer (node:https:105:10)
    at ProxyServer.listen (C:\Users\justintoth\AppData\Roaming\npm\node_modules\iisexpress-proxy\node_modules\http-proxy\lib\http-proxy\index.js:129:11) {
  library: 'SSL routines',
  function: 'SSL_CTX_use_certificate',
  reason: 'ee key too small',
  code: 'ERR_SSL_EE_KEY_TOO_SMALL'
}

Does this tool still work and I'm just missing something obvious?

VPN functionality not working

My server is connected to a VPN and I tried using your method of using the command but I can't seem to connect to the server while it's in the VPN. I'm still trying to understand how IIS is used when the machine is connected o a proxy but I don't have any luck fixing the problem.

instead of ip, name based urls

my ip changes.

can't i use my pcname instead? thnx?