README.md

   1 # BindIP
   2 This program allows you to assign network interface (ie "source IP address")
   3 for each application in Windows. You can have one program routed through wifi,
   4 another through wired connection, next through a VPN ...
   5
   6 It started as a spiritual sucessor of http://old.r1ch.net/stuff/forcebindip/
   7 which was too feature limited and closed sourced, thus impossible to fix.
   8
   9 Some of the new features are:
  10 * Hooks all the winsock APIs, not only selected few (WinSock helper filter)
  11 * Supports both 32 and 64 bit applications
  12 * Configuration changes take effect immediately without restarting applications
  13 * Reflect ip switch (ie via dhcp after VPN reconnect) immediately too
  14 * Child processes can inherit binding of parent processes
  15 * GUI
  16
  17 # TODO / known bugs
  18 * Windows 8/10 support. We need to do a full filter which is immense PITA. Patching mode is unreliable too.
  19 * Rewrite Makefile to actually use MINGW. Current version is result of my poor
  20   understanding of MSYS/MINGW
  21
  22 # Building
  23 You need MSYS2 and 64bit windows. Just `pacman -S gcc` and `make`. To sign the dlls, you need to create your
  24 snake oil cert. I didn't include kat.pfx to avoid malicious parties abusing it if you trust my snake oil.
  25
  26 # Usage
  27 ![screenshot](http://i.imgur.com/1aXj9pA.png)
  28
  29 In the list to the left you select an application you want to configure (it is
  30 a multiselect list, hold ctrl to configure more at once), in the right list
  31 click on interface to assign (or 'default route' to remove assignments).
  32
  33 You can also set two global options:
  34
  35 *Global Winsock hook* - with this checkbox, all network applications will be
  36 affected with settings you configure automatically. It is off by default and
  37 you need admin privileges to enable this setting, otherwise the second option
  38 can be used. Note that for applications which run with elevated privileges
  39 (such as VirtualBox) you generally want to use this, as per-application
  40 injection often does not work in that case.
  41
  42 *Add right-click option to shell explorer* - with this enabled, you'll see
  43 this when right clicking an application icon shortcut/executable:
  44
  45 ![popup](http://i.imgur.com/gfteqV2.png)
  46
  47 You have to run program you want affected by BindIP through this menu item,
  48 unless you have enabled *Global Winsock hook*.
  49
  50 Finally, you can just prefix stuff you run on command line with `bindip`, ie
  51
  52 ```bash
  53 $ bindip git clone http://some.place/repo
  54 ```
  55
  56 When using shell extension/command prefix, child processes which don't have
  57 explicitly configured binding will inherit it from parent process.
  58
  59 This inheritance is controlled through `BINDIP_EXE` environment variable, which
  60 is just set to some .exe basename, same as seen in the left panel  of the gui.
  61
  62 Any program which sees this variable assume identity configured in there. Windows
  63 passes environment on children so everything in process tree will see the same
  64 value.
  65
  66 You can of course create shortcuts where program path is prefixed with bindip,
  67 or without it (with global hook enabled) - just setting custom BINDIP_EXE is
  68 enough. Note that without the environment, inheritance does not work (ie when
  69 using global hook, you're advised to create shortcuts with BINDIP_EXE set).
  70
  71 # Setting up default interface
  72 When a program has no particular interface selected, ie *(default route')*,
  73 system will choose one based on "interface metric". To change the preferred
  74 default route, first figure out which interface it actually is:
  75
  76 ```cmd
  77 C:\> route print
  78 ...
  79 IPv4 Route Table
  80 ===========================================================================
  81 Active Routes:
  82 Network Destination        Netmask          Gateway       Interface  Metric
  83           0.0.0.0          0.0.0.0          10.0.0.1      10.0.0.2   10
  84           0.0.0.0          0.0.0.0          192.168.0.1   192.168.0.2 20
  85 ....
  86 ```
  87 Notice the `Interface` and `Metric` columns.
  88 10.0.0.2 is my wired connection, and 192.168.0.2 is VPN. The VPN metric is
  89 higher, which means it is not a preferred default route (only used by apps
  90 who have it explicitly assigned with BindIP). Wired connection has the lowest
  91 metric and is thus used as default when there is no override assignment.
  92 To change this arrangement, I can click 'View network connections' control panel,
  93 find the adapter with that ip (10.0.0.2 in this case):
  94
  95 ![metrics](http://i.imgur.com/2oVTnKZ.png)
  96
  97 Click on *Internet protocol version 4 (TCP/IPv4)*, then *Properties*, then
  98 *Advanced*, then uncheck *Automatic metric* and put some number in the field.
  99 With manual metrics we can determine the order in which interfaces take
 100 precedence as default - the lowest number wins. In this case, metric was
 101 changed to 50, after closing all 3 dialogs we get:
 102
 103 ```
 104 C:\> route print
 105 ...
 106 IPv4 Route Table
 107 ===========================================================================
 108 Active Routes:
 109 Network Destination        Netmask          Gateway       Interface  Metric
 110           0.0.0.0          0.0.0.0          192.168.0.1   192.168.0.2 20
 111           0.0.0.0          0.0.0.0          10.0.0.1      10.0.0.2   50
 112 ....
 113 ```
 114 And now the VPN takes precedence (is used for everything), because of the
 115 lowest metric number. Without explicitly setting it, windows configures
 116 metrics automatically, see https://support.microsoft.com/en-us/kb/299540
 117
 118 Caveat: Sometimes, broken VPN software will set two more specific default
 119 routes (0.0.0.0/1 and 128.0.0.0/1 destinations) as means to override all
 120 other default routes regardless of metric. This is harmful kludge or
 121 misconfiguration, and should be fixed on the part of the VPN provider, as
 122 users can no longer configure their preferred default route.
 123
 124 # Code signing
 125 Some applications (VirtualBox does this) and antivirus software
 126 and domain policies permit only signed DLL to be loaded. To make
 127 this work, download ceriticate from
 128 https://github.com/katlogic/bindip/raw/master/katCA.cer and run:
 129 ```
 130 > certutil.exe -addstore Root katCA.cer
 131 ```
 132 Which will make the distributed DLLs trusted. MSI installer does
 133 this automatically for you.
 134
 135 # FAQ
 136 > Is it possible to add a switch so you can choose the adapter or "IP" address the application goes out rather then metric ?
 137
 138 You can configure the bindings programatically via registry - HKCU\Software\BindIP\Mapping. Note that adapters are mapped by GUID internally. To get GUIDs mappings, you can use WMI. In powershell:
 139
 140 ```
 141 PS C:\Users\kat> Get-WmiObject  -Class Win32_NetworkAdapterConfiguration -ComputerName . | Select-Object -Property SetingID,Description,IPAddress
 142
 143 SettingID                              Description                            IPAddress
 144 ---------                              -----------                            ---------
 145 {12345678-1234-1234-1234-123456789121} Microsoft Kernel Debug Network Adapter
 146 {12345678-1234-1234-1234-123456789122} Intel(R) PRO/1000 MT Desktop Adapter
 147 {12345678-1234-1234-1234-123456789123} Microsoft ISATAP Adapter
 148 {12345678-1234-1234-1234-123456789124} Microsoft Teredo Tunneling Adapter
 149 {12345678-1234-1234-1234-123456789125} Realtek PCIe GBE Family Controller     {10.0.0.8}
 150 ```
 151
 152 The value you're lookign for is SettingID. Then in cmd:
 153
 154 ```
 155 C:\> REG ADD HKCU\Software\BindIP\Mapping /f /v someexe.exe /t REG_SZ /d {12345678-1234-1234-1234-123456789125}
 156 ```
 157
 158 This is the equivalent of clicking an adapter `Realtek PCIe GBE Family Controller` when `someexe.exe` is selected in the GUI.
 159
 160 You can create some fake exe name for each adapter, ie:
 161 ```
 162 C:\> REG ADD HKCU\Software\BindIP\Mapping /f /v intel_nic.exe /t REG_SZ /d {12345678-1234-1234-1234-123456789122}
 163 C:\> REG ADD HKCU\Software\BindIP\Mapping /f /v realtek_nic.exe /t REG_SZ /d {12345678-1234-1234-1234-123456789125}
 164 ```
 165
 166 And then when you need to bind specific NIC, just:
 167
 168 ```
 169 C:\> set BINDIP_EXE=intel_nic.exe
 170 C:\> someapp.exe
 171 ```