White Label Service Guide

2016-11-16, 11:16

• Introduction
  • What is PageKite
  • Why white-label?
• Getting Started Checklist
  • Register a domain
  • Delegate DNS to PageKite nameservers
  • Pay the setup fee and subscribe to the service
  • Create your Temporarily Unavailable page
  • Choose an encryption strategy
  • Choose your account management strategy
  • Integrate PageKite into your product
  • Think about geography
• Account Management Strategies
  • Preconfigured Accounts
  • Device-Registered Accounts
  • Centrally Managed Accounts
  • One PageKite.net account or many?
• Product Integration
  • libpagekite
  • pagekite.py
  • XML-RPC API

Introduction

The PageKite white-label service allows people to rebrand the PageKite.net public relay and dynamic DNS services.

This document is explains the basics of how the PageKite white-label service can be used in your work.

What is PageKite

PageKite is an Open Source reverse-proxy system which makes local servers visible to the public Internet, without requiring the origin server have a public IP address and usually without requiring any reconfiguration of intervening firewalls.

Use cases include:

1. Allow devices in the home to be configured using a web browser, even if the browser and device are on different networks.

2. Create a channel which allows mobile apps to communicate with devices in the home or behind firewalls or NAT.

3. Remote management of devices without a public IP address (SSH).

PageKite can relay HTTP and TLS (HTTPS) connections directly, and can relay other TCP-based protocols (including SSH) indirectly by making use of the HTTP Proxy protocol.

The PageKite.net service provides a fully managed global network of relay servers, along with auxillary support systems such as dynamic DNS and account management systems. The service infrastructure is monitored 24/7 and has a mature, decentralized architecture allowing it to automatically recover and route around both network and server outages. It has been in continuous operation since 2010.

Why white-label?

In its most basic form, white-labeling means when an end-user would normally expose a local web server using a URL of the form username.pagekite.me, they would instead use username.your-kite-domain.me.

This serves two purposes:

1. Protect your brand and reduce end-user confusion.

2. Avoid becoming locked-in and irrevocably dependent on the services provided by The Beanstalks Project ehf at https://pagekite.net.

The first point needs little explanation; in short, users of a product built upon the white-label PageKite service will not be exposed to PageKite branded domains or messages. For users of your product, PageKite is plumbing and bothering them with such technical details is usually just a recipe for confusion.

The second is reason more involved, but is arguably more important: once thousands of devices have been deployed, it can become difficult to change their configuration and in particular it could become difficult to switch to another provider of relay and dynamic DNS services.

The recommended white-label configuration (see product integration below) introduces a layer of abstraction; the white-label domain, which is used for configuration. As ownership and ultimate control of this domain remains with you, this gives you the freedom to take your business elsewhere if necessary.

---

Getting Started Checklist

• Register a domain
• Delegate DNS to PageKite nameservers
• Pay the setup fee and subscribe to the service
• Create your Temporarily Unavailable page
• Choose an encryption strategy
• Choose your account management strategy
• Integrate PageKite into your product
• Think about geography

Register a domain

For example: your-kite-domain.me

In order for the PageKite.net white-label service to work, you need to select a DNS domain name; in this document we use your-kite-domain.me as an example, but obviously you will choose something more fitting for your product.

You will be able to configure your clients to use any subdomain under that domain for their connections, according to a policy of your choosing; see account management strategies below for details.

Note that the domain name will belong to your business and you will retain ownership and ultimate control over it. This is a key feature of the white-label service: if necessary, you will be able to move your clients to an alternate relay service by changing the DNS servers for this domain.

Delegate DNS to PageKite nameservers

The PageKite nameservers are:

• ns1.pagekite.net
• ns2.pagekite.net
• ns3.pagekite.net

The PageKite.net white-label service will provide dynamic DNS service for the domain (necessary so devices can switch relays to adapt to changing network conditions), which is why you need to delegate the domain to PageKite's name servers.

Once you have registered a domain and delegated the DNS, you should notify help@pagekite.net, so we can configure things at our end. Note that no changes will be made until you complete the next step: payment.

Pay the setup fee and subscribe to the service

When PageKite service is purchased in bulk, as is generally the case with white-label configurations, significant discounts are available compared with our individual and team prices.

White-label serivce and bulk pricing start with the embedded subscription plan, for $199.95 USD/month. This allows you to connect up to 500 devices to the PageKite network, or $0.40 USD/month per device. For larger volumes, prices go down even further - but we can't give detailed quotes until we know more about your application. Five hundred devices should be enough for development and beta testing, which also gives us time to figure out what your needs are.

White-label customers have the option of being paying using a recurring credit card subscription, or being invoiced once per quarter and sending us wire-transfer payments in Euros, US Dollars or Icelandic Krona.

Starting Small

If your business is very early stage and you only need to connect a small of devices for the first few months, as you develop your product, you can still sign up for white-label service by paying a one-time setup fee of $200 USD, and subscribing to one of the smaller subscription plans.

Customers who intend to take advantage of this option should get in touch and let us know.

Then log in to your account, purchase the subscription plan you prefer and then use the "pay-what-you-want" form on https://pagekite.net/pricing/ to make a one-off $200 USD payment.

Note that to keep our overheads low, quarterly invoicing is not available to users who "start small" (generating and sending invoices is a manual process).

Create your Temporarily Unavailable page

Create a publicly visible web-page for the "Temporarily Unavailable" message displayed to your users when their kite is offline.

When a user tries to load a page which is unavailable for some reason, this page will be displayed. The error can be generated either at the front-end relay, or at the back-end (on your device).

You can differentiate between the two errors by consulting the URL query-string variables.

• If the error was generated by the back-end, where=BE will be set. This generally means pagekite.py or libpagekite are misconfigured, or the origin web-server is not running for some reason.
• If the error is generated by the front-end relay, where=FE will be set. This means the relay server does not have a working pagekite connection for the protocol and domain requested. This can be a sign of misconfiguration, a sign of network troubles or a sign that pagekite.py or libpagekite aren't running.
• In both cases, there will also be proto=HTTP and domain=kitename.your-kite-domain.me. The protocol may also be HTTPS in some cases.

An example (split in two lines for readability):

http://yourdomain.com/pagekite-offline/?
where=BE&domain=kitename.your-kite-domain.me&proto=http

Once your error page is live, send the URL to help@pagekite.net, so we can update your account settings.

Choose an encryption strategy

As PageKite connections are routinely used to grant remote access to devices in the home or inside business networks, it is important to protect the communications and any relevant credentials from eavesdropping. The industry standard way to do this for the web, is TLS (a.k.a. SSL), which both encrypts the communication and authenticates the remote server to prevent impersonation.

We highly recommend that any HTTP (web) traffic sent over PageKite be encrypted; either by using a wild-card certificate on the PageKite relays or by deploying individual certificates to each device.

The wild-card certificate is less secure, in that the PageKite relays themselves will have access to unencrypted data. However, it is far better than no encryption at all, and is significantly easier to manage than a certificate on each device. It is also compatible with HTTPS clients that do not support the TLS SNI extension.

If you have the option to deploy an individual certificate on each device (for example using https://letsencrypt.org/), this is the most secure solution as it will prevent even the PageKite relays from seeing or modifying the contents of user communication. This option requires the clients support the TLS SNI extension (which all modern browsers do, but some other HTTP clients may not).

For further advice on TLS, SSL, compatibility and key management, get in touch. If you do decide to purchase a wild-card TLS certificate for your white-label, get in touch and we will send you a CSR - certificate signing request so sensitive key material doesn't have to be sent accross the Internet.

Choose your account management strategy

This is a large topic. Please see the section below for details.

Integrate PageKite into your product

This is a large topic. Please see the section below for details.

Think about geography

The performance of PageKite depends to a significant degree on how far the relay servers are from the origin servers (the machines running pagekite.py or libpagekite).

Although the PageKite.net service provides global coverage, we can provide better service if you let us know roughly where in the world you expect your users to be. Today we have very good coverage in Europe and North America, and some coverage in Asia and Australia.

By default, PageKite will choose the fastest (closest) relay for your users automatically. If you have different needs (for example if you require all traffic be relayed through Europe) or you expect a significant amount of traffic from a region we don't currently support, just let us know and we'll make the appropriate changes to your configuration and roll out new relays as needed.

---

Account Management Strategies

Each devices or application which connects to a PageKite public relays needs two things:

• One or more unique kite names (DNS domains)
• A shared secret used to sign authentication challenges

How these are provisioned to new users of your product varies; three of the most common strategies are discussed below.

Preconfigured Accounts

The simplest and most secure account management strategy, is to preconfigure accounts before devices are shipped to the end-user.

Kite names and shared secrets can be derived from device serial numbers or be randomly generated. Note that if a predictable function is used to generate the shared secrets, you risk widespread compromise of your device credentials if the generation algorithm leaks or is stolen. Random secrets are therefore strongly preferred.

The XML-RPC API can be used to provision and configure the accounts automatically in bulk.

Device-Registered Accounts

It is possible to configure devices so they register a new PageKite account when they first come online.

This has the advantages that the PageKite.net accounts will exactly match the number of deployed, live devices. It also simplifies software/device deployment and avoids the need for a central management server.

The disadvantage of this approach, is it requires the system either be configured for unauthenticated registration of new accounts or requires that deployed devices include a "secret key" which permits registration.

If this key leaks (or unauthenticated registration is allowed), anyone will be able to register illegitimate accounts. This problem can be mitigated by monitoring, but note that such monitoring is not currently included in the PageKite.net solution, as it is generally highly application specific.

Centrally Managed Accounts

Some service providers have their own management systems or customer portals, either customer-facing or for internal use.

In either case, it often makes sense to extend the service portal to include management of user PageKite accounts.

The XML-RPC API can be used to implement such integration.

One PageKite.net account or many?

The PageKite.net service has its own concept of user accounts, which white-label customers can use in two different ways.

1. A single PageKite.net account can have as many kites as necessary, and each kite can be assigned a different shared secret.

2. Individual PageKite.net accounts can be created for each end-user or deployed device.

The first case is in many ways simpler and is generally preferred by users using Centrally Managed Accounts as it simplifies integration. It has the drawback that PageKite's quota control systems cannot easily be used to prevent individual accounts from consuming excessive resources.

The second case is more appropriate when using Preconfigured Accounts or Device-Registered Accounts. In this case there is generally a master account which "sponsors" the others usage, but alternate strategies may be more appropriate for applications where there is a potential for excessive resource consumption or abuse.

---

Product Integration

libpagekite

Libpagekite is a high-performance reimplementation of PageKite in C. It includes Python bindings and Java JNI bindings, in addition to the native C interface.

Libpagekite is still a work in progress, but the code required for running a PageKite connector is relatively stable and is in many ways better than the legacy Python code. This is the future of PageKite development, so if you are creating a new product we recommend starting here.

The API documentation is quite detailed, but take special note of the method named pagekite_init_whitelabel, which will at any given time implement the current best practices for connecting to a PageKite.net white-label (or compatible self-hosted) service.

If you are using the included pagekitec connector client (or code derived from it), the -w flag can be used for white-label initialization.

pagekite.py

In this section, we assume you are using the PageKite Debian package; it already handles starting up on boot, logging and restarting PageKite when it crashes.

Below are the recommended settings for a white-label pagekite.py deployment, assuming your white-label domain is your-kite-domain.me. By configuring pagekite.py this way, you guarantee that you will be able to migrate your clients to private infrastructure at a later date without changing their configurations (as discussed in the introduction).

These lines should go in /etc/pagekite.d/20_frontends.rc:

frontends=1:fe.your-kite-domain.me:443
dyndns=http://dnsup.your-kite-domain.me/
       ?hostname=%(domain)s&myip=%(ips)s&sign=%(sign)s
ca_certs=/etc/ssl/certs/ca-certificates.crt
fe_certname=fe.your-kite-domain.me
fe_certname=your-kite-domain.me
fe_certname=pagekite.me

Notes:

• Be sure to delete or comment out the defaults setting
• The dyndns line is wrapped for legibility, it should all be on one line.
• If you have provided us with a wild-card certificate for your domain, we recommend using the HTTPS protocol instead of HTTP for dynamic DNS.
• The final fe_certname line (for pagekite.me) may be omitted if you have provided us with a wild-card certificate for your domain.
• If you are not using Debian or Ubuntu, you may need a different ca_certs path.

XML-RPC API

The PageKite.net XML-RPC API can be used to create and manipulate kites (DNS names) and accounts.

The API reference can be found here: https://pagekite.net/xmlrpc/