Applications

Some services only let you in from your institution’s network: library databases such as JSTOR or ProQuest, licensed research tools, vendor portals. Applications send traffic for just those services through a gateway machine on that network, so the vendor sees the gateway’s public IP address. Everything else on the device keeps going straight to the internet as usual.

Unlike an exit node, which carries all internet traffic, an application only covers the domains you list for it.

How it works#

1. When a device looks up one of the application’s domains, the lookup goes through the encrypted tunnel to the gateway instead of to the usual DNS server. TxHub sets this up for you, alongside your other DNS settings.
2. The gateway looks the name up from its own network and answers. It then starts offering the address it learned as a route.
3. TxHub approves these routes automatically, together with any static routes the application has, and sends them to your devices within seconds.
4. The device’s connection to that address goes through the tunnel and leaves the internet from the gateway. The vendor sees the gateway’s public address.

Turning an application off, or removing it, withdraws its DNS rules and routes straight away. Traffic to its domains goes direct again.

Every device in the TxNet uses active applications automatically. The access policy doesn’t need a rule for them.

Set it up#

1. Prepare the gateway machine

The gateway should be an always-on Linux machine on the network the vendor recognises, for example a small server or virtual machine inside your institution. While the gateway is offline, devices can’t look up the application’s domains, so the application stops working.

1. Install TxHub on the machine and connect it to your TxNet.

2. Turn on IP forwarding for IPv4 and IPv6, and save it so it survives a reboot:

   $ echo 'net.ipv4.ip_forward = 1' | sudo tee /etc/sysctl.d/99-txhub.conf
   $ echo 'net.ipv6.conf.all.forwarding = 1' | sudo tee -a /etc/sysctl.d/99-txhub.conf
   $ sudo sysctl -p /etc/sysctl.d/99-txhub.conf

3. Make the machine an application gateway:

   $ sudo txhub set --advertise-connector

   On Windows or macOS, turn on Application gateway (macOS: Application Gateway) in the TxHub app instead, under Advanced. This is fine for trying things out; see Good to know for why Linux is better for real use.

4. On Linux the command may print a warning that UDP GRO forwarding is suboptimally configured. Forwarding still works, but you can improve throughput by running this, with your network interface in place of eth0:

   $ sudo ethtool -K eth0 rx-udp-gro-forwarding on rx-gro-list off

   This setting is lost on reboot unless you add it to your network configuration.

2. Add the application in the dashboard

Only owners and admins of the TxNet can manage applications.

1. Go to Settings → Applications.
2. To use a ready-made application, find it under Catalog and click Add. For your own domains, click Add custom application and fill in a Name, the Domains (one per line) and, if needed, Static routes.
3. Under Gateway machine, choose the gateway you prepared. Machines already acting as a gateway are marked Gateway ready.
4. Click Add (catalog) or Add application (custom).

The application appears under Enabled. Its card shows the status:

Use the switch on the card to turn an application off and on, Change gateway to move it to another machine, and the pencil to edit a custom application’s domains and routes. Catalog applications are maintained by TxHub and can’t be edited.

3. Check that it works

On the gateway, confirm it is running as an application gateway:

$ txhub debug prefs

The output should contain "AppConnector" with "Advertise": true.

On a device, check that lookups for the application’s domains go to the gateway:

$ txhub dns status

Each of the application’s domains should be listed with a resolver like http://100.x.x.x:port/dns-query, the gateway’s TxNet address.

Then open the service, and check where the traffic goes. On macOS, look up the service’s address and ask which interface it uses. A utun interface means it goes through TxNet:

$ route -n get 203.0.113.7

What devices need#

• DNS settings from TxHub. Devices accept these by default. If you turned them off on Linux, turn them back on with sudo txhub set --accept-dns.
• Subnet routes turned on. On Windows and macOS, Use subnet routes must be on in the TxHub app (on by default on Windows). On Linux, run sudo txhub set --accept-routes. See Subnet routes.

Good to know#

• The vendor must recognise the gateway. Register the gateway’s public IPv4 address with the vendor, or place the gateway behind the address your institution has already registered.
• IPv6. If the gateway has IPv6, devices may connect over IPv6 and the vendor sees the gateway’s IPv6 address. If the vendor only accepts IPv4, register the IPv6 address too or make Linux machines prefer IPv4 by adding precedence ::ffff:0:0/96 100 to /etc/gai.conf.
• The first connection can go direct. A route is only created after the first lookup, so the very first connection may leave before the route arrives. If you know the vendor’s addresses, add them as Static routes so they always go through the gateway. Static routes must be public and can be at most a /16 for IPv4 or a /48 for IPv6; an application can have up to 64.
• Cached lookups after turning an application on. A device that looked up the domain while the application was off keeps using that answer, and goes direct, until it expires. Flush the DNS cache to start over:

  # macOS
  $ sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
  # Windows (Command Prompt)
  $ ipconfig /flushdns

• Wildcards. *.example.com matches subdomains only, not example.com itself. When you enter a wildcard, TxHub adds example.com for you.
• Some domains can’t be used. Domains that overlap TxHub’s own hostnames, reserved names, your TxNet’s DNS domain, a DNS zone or split DNS domain, or another enabled application are refused when you save.
• Learned routes are shared per gateway. All applications on the same gateway share the addresses it learns, so the number of learned routes on a card is approximate. On the gateway’s machine page, the learned addresses also appear under Subnet Routes as not yet approved. You don’t need to approve them: TxHub approves application routes automatically.
• Why not a Mac or a laptop? A laptop moves between networks and sleeps, so the vendor sees a different address or nothing at all. On macOS forwarding also runs in software rather than in the system, which is slower and less tested. Linux is the supported platform for gateways.