Setup Nebula VPN

You should have at least 2 devices with Nebula installed and showing their device setup screens.

Java Android Arduino
Java (JAR) Android (APK) Arduino (BIN)

Above are the installation windows for JAR, APK and BIN devices. For JAR and APK you can select whether the device is to be setup as Device 1 or if it’s being added to an existing Nebula VPN. A BIN device cannot serve as Device 1, it can only be added to an existing Nebula VPN. You can enter a name for the device now or at any point during the installation setup. APK devices running Android version 6 or higher will prompt for the user permissions required to run all the demonstration commands. Upon selection of either Device 1 or Add to VPN, the screen will show additional appropriate setup widgets.

Device 1

Think carefully about choosing Device 1 as it acts as the hub for your VPN. The hub is what allows you to control devices on your VPN when you are away or mobile. Device 1 is also the master for the VPN device database. Other devices will sync with it each time their Nebula app is started. Mobile devices report their “home” or “away” status to Device 1 who in turn will update the other devices on the VPN. Review the notes below then continue.

  • Device 1 should use DNS for its public address and a reserved local address. See Setup Router for how to do this.
  • Device 1 should always be “home”, always be powered on, and always running Nebula. The display can sleep but the processor cannot sleep as that kills the Nebula process.
  • Nebula can be minimized i.e. not showing but must be a running process.
  • Three ports, A Base Port for commands and the next two consecutive ports for stream-in and stream-out will be forwarded to Device 1 through your router.
  • While Nebula is secure other programs may not be, so best is not to run other networking programs on it that may be susceptible to hacking.
  • Recommended is a desktop running Ubuntu Linux, a Beagleboard running Debian, or a Raspberry Pi running Raspian.
  • Windows, MacOS or Android with Developer option Stay Awake on, work too.
  • Device 1 can be any JAR or APK device. It cannot be an Arduino or NodeMCU device.
  • Device 1 is a fully functional Nebula device so it can still be a security camera, thermostat etc. while acting as the VPN hub.
  • If Device 1 has a public static IP address it must also be able to contact all devices connected to its home network using their private address. Mobile devices sending commands to home devices use Device 1 as the relay hub. Contact Galixsys Networks for any special VPN services.
  • Decide which of your devices is going to be Device 1 and referring to the balance of this page, install it first.

Adding Devices

It should be apparent from the installation of Nebula that there are 3 distinct versions that are based on the Operating System (OS) of the host device.

1. Java - Runs on the Linux, Windows or Mac OS platforms. It may also be referred to as the JAR version with the host referred to as a JAR device.

2. Android - Runs exclusively on any phone, tablet or device running the Android OS. It may also be referred to as the APK version with the host referred to as a APK device.

3. Arduino - Runs on any device that can be programmed using the Arduino Integrated Development Environment (IDE). It may also be referred to as the BIN version with the host referred to as a BIN device. BIN devices cannot be used as Device 1. Their install screen is provided by a webpage as shown above. They only require a device name and the address:port, don’t forget the colon, of Device 1 to install.

Quick Start

Start VPN with Device 1:

Java2 Android2
Java (JAR) Android (APK)
1. Enter a name for the device.
2. Use the default Base Port or enter your own.
3. Check Uses Database. Demonstration database commands require a database on Device 1.
4. Optionally check Use Crypto to encrypt network data.
5. Click the Public IP text box; use the discovered public IP or enter a DNS address.
    5.1. DNS is better because your ISP may change the public IP. Big problem for VPN.
6. Select the network connection if more than 1 is available.
7. Click EXECUTE.
8. Review the install log.
9. Click EXIT to go to the Running screen.

Add Device to VPN:

Java3 Android3 Arduino2
Java (JAR) Android (APK) Arduino (BIN)
1. Enter a name for the device.
2. Enter the address:port of Device 1.
    2.1. Device 1 local address if adding a device that's on the same local network.
    2.2. Device 1 public address or DNS name if adding a device that's remote.
    2.3. Base port must be forwarded to Device 1 to add a remote device.
3. Select the network connection if more than 1 is available.
    3.1 Check static if adding a cloud server instance or true static IP device.
4. Confirm your Email Credentials if the device can go mobile.
5. Click EXECUTE.
6. Review the install log.
7. Click EXIT to go to the Running screen.

Prompt Window

The top section of the Java and Android setup screen is a scrollable window where user prompts, detailed instructions, error messages and installation results are shown to the user.

Device Name

Every Nebula device requires a unique name. The name can be any combination of upper and lower case letters and numbers. The name cannot include the Nebula reserved characters comma(,), up-caret(^), colon(:) or forward-slash(/). It can include spaces and other symbols. It must be at least one character but has no maximum length restriction. Note that names longer than 24 characters may appear messy on the Running window. Short descriptive names like Living Room Switch-1, Office Camera or Jane’s Phone are best.

Base Port

Device 1 sets the Base Port for the VPN. All Nebula devices connected to the VPN will send and receive commands over the Base Port. All devices will use the next two consecutive ports for streaming data. So if the Nebula Base Port is the default 50500, then ports 50501 and 50502 will be used to support the transfer of data streams.

A full list of port numbers and their use can be found here. The command port number must support TCP (Transmission Control Protocol). User Datagram Protocol (UDP) is optional and not used in base Nebula. The basic difference between TCP and UDP is that TCP insures that data arrives, over the Internet, uncorrupted while UDP makes no such assurance. Android restricts the use of Well-known port numbers (0 - 1023) unless the device has been rooted.

Security is mostly a concern for Device 1 as in most cases it will be the only device exposed to the public internet. Devices that stay home, behind your router, cannot be seen publicly so their port number is of little concern. It’s a good idea to stay away from registered port numbers (1024 to 49151) unless you are sure of it. Hackers look for access on known alternates like port 8080.

The Nebula default port (50500) is in the private range (49152 to 65535). Picking an obscure port number aids in security. It’s known as “Security by Obscurity.” All devices will use the same port numbers defined on Device 1. Instructions on how to forward the port numbers you choose for Device 1 is covered later in this document. BIN devices initially use port 80 to present their installation screen via a webpage viewed by your browser. Upon installation they will be notified of the selected Base Port and use it for command and data transactions while running Nebula.

Checkbox - Uses Crypto

This checkbox is only available for Device 1. If checked for Device 1 then all JAR and APK devices on the VPN will use encryption for their public and private command transactions. Streaming data is not encrypted beyond the compression algorithm used and the unique Unicode Transformation Format (UTF) code separating frames of data. Nebula does not encrypt transactions to or from BIN devices. They are typically light on memory and hidden behind a router. The Device 1 hub action will encrypt or decrypt public network data to or from BIN devices.

The example code of Nebula uses AES_CBC encryption. Device 1 makes a unique “secret key” that it shares during installation with all other devices on the VPN. For every data transaction, both sending and responding, individual devices make an Initialization Vector(IV) key that is sent with the encrypted command protocol. This IV key can be referred as the “public key” and does not have to be kept secret as it changes on every transaction.

Encryption and decryption take time so think about your application and try it with and without encryption. Contact Galixsys Networks for additional and alternative security requirements.

Checkbox - Requires Database

See Databases to get an overview of Nebula requirements for database usage. If checked on an APK device Nebula will set-up and establish a minimal (SQLite) database for test and verification purposes. If checked on a JAR device it will verify that either MySql or MariaDB server is installed and attempt to connect to it with user=nebula and password=nebula. If it can connect the minimal database will be setup and you will get the response, “Success Database created”. If a database is not installed or the JAR device cannot connect to it with the demo credentials you will get a non-fatal response, “FAIL creating database.” JAR devices can install a database at any time, APK devices must check “Requires Database” at installation and BIN devices do not support a hosted database, they must upload data to either an APK or JAR device database.

Android devices have MPAndroidChart implemented for display purposes. Java devices have a simple line chart class implemented for display purpose. The minimal DB used for demonstration implements 3 string columns for date/time | deviceName | data.

Select the Host IP Address

Devices can have multiple valid IP addresses like WiFi and Ethernet at the same time. Nebula searches the device for all valid, meaning those that can connect to the Internet, addresses. If there is more than 1 address you can click the Net number button to select the address you want other devices to use to contact this device. The Prompt Window will show the name (wlan0, eth0 etc.) of the network connection and the IP address Text Box will show the address the device will use.

IP Address Text Box

Shows the home IP address of this device that other devices on the VPN will send commands to. The Text Box is only editable if Static IP is checked. You can enter either a public or private IP address if you are sure that the device will eventually be connected to it.

Checkbox - Static IP

Nebula has been verified with a VPN member device running on a Cloud Server instance. An instance runs on a private network but has a public static address attached to it. Checking the Static IP box forces the use of the public static address. The intended primary use is to provide for a Cloud-based database on your VPN for applications requiring large data arrays.

SMS Email for Mobile Device

The JAR and APK setup screens are nearly identical. The one difference is that the APK has a line for SMS Email. This is due to APK device’s ability to go mobile. When an APK device goes mobile its IP address is restricted by the service provider. Unless the device has a static IP address, it can only act as a client sending requests and receiving responses over the Internet. Nebula can send commands to mobile devices directly via uniquely coded SMS (text) messages. If you give the device SMS READ permission, you will hear the incoming text tone, the command will run automatically and the message (encoded command) will be in your SMS conversations.

Nebula detects if an APK device can go mobile, what its phone number is, who the provider is, and the email address the provider uses to forward the message to the device. It takes the form of email ie. PhoneNumber@ProviderEmail.ext and is shown on the SMS Email line of APK devices. It can be edited if it is incorrect and will appear as NONE if the device cannot go mobile, SMS READ permission is denied or you just enter NONE on the line. In order to send an email you must have a valid email account. To automatically send an email you have to provide Nebula with:

  1. Email host server - The outgoing email server. Example:
  2. Your email account address - Example:
  3. The account password - It’s secure but best to have an email account just for Nebula.

If an APK device can go mobile, Nebula will prompt you to enter and save the email credentials.

  1. If the PhoneNumber is shared, also referred to as linked, that is multiple devices receive all SMS messages, then multiple devices will also receive the commands. Nebula devices only respond to commands intended for it. Commands that come in via SMS not intended for the device are not rerouted, they are ignored.
  2. Leaving a field blank, or entering “NONE” will prevent Nebula from sending commands to a mobile device.
  3. Use a computer that has email setup on it and send a test email to <phoneNum>@ProviderEmail.ext. Verify it comes in as SMS (text) message.
  4. Nebula built-in providers and email are:
Alltel:     <phoneNum>
AT&T:       <phoneNum>
Boost:      <phoneNum>
Nextel:     <phoneNum>
Cricket:    <phoneNum>
Sprint:     <phoneNum>
Tracfone:   <phoneNum>
T-Mobile:   <phoneNum>
Verizon:    <phoneNum>
Virgin:     <phoneNum>

Edit Email Credentials Button

Nebula automatically prompts for email credentials as explained above, but if you make an entry error or want to change or just verify the email account, you can use this button to recall email account entry dialog.


Click this button when all the setup selections appear correct. The Prompt Window will show a log of the install ending with Success or Failed. If successful the EXECUTE button will be disabled to prevent installation of the same device multiple times if you happen to double click the button.

EXIT Button

Click this button when you want to leave the Setup screen. If the device has not been fully or successfully installed, you will get an error prompt stating “No Devices.” If the setup was successful and the device was installed, Nebula will go to its Running window and the device will be available to send and receive commands.

Android Permissions

If your phone or tablet is running Android version 6 or higher you must give permission for Nebula to use some features. The following is a list of the required permissions and why they are needed by Nebula. Remember, Nebula is your private network. No data can be sent or read outside the VPN you setup without you having programmed a device to send it or allowed others to read it.

1. Body Sensors - Allows Nebula to read the available sensors on your device. The data may be used by you to upload to a VPN database, display to a user or other uses as determined by an app you develop. Current Nebula simply lists, in the log output, all the sensors and their type available on a device.

2. Camera - Nebula has demonstration code that allows streaming video from one VPN device to another VPN device. You may also want to code your VPN devices to pass photos or use the camera to detect motion.

3. Location - Nebula has demonstration code to get the latitude and longitude of a VPN device and show a map location of where the device is. Beyond granting permission, location services must be enabled on the Android device.

4. Microphone - Nebula has demonstration code that uses voice control to monitor and / or control other VPN devices. Nebula uses the built-in Android (Google) voice recognition classes to convert speech-to-text.

5. Phone - Mobile Nebula VPN devices that do not have a static IP address receive encoded commands via SMS messages. Mobile devices send commands via HTTP.

6. SMS - Mobile Nebula VPN devices check SMS messages for command coding and if it exists, will execute the received command automatically.

7. Storage - Nebula devices maintain database files of the VPN and how to contact other devices attached to the VPN.

Full Disclosure

The Nebula Demo application uses the Internet for the following purposes.

1. To verify network Internet connectivity - sends 1 ping to

2. To get the device public IP - sends http GET to<private page>. The following PHP code is run. You are welcome to copy and run it on your own public server.


    $ip = getenv('HTTP_CLIENT_IP')?:
    echo $ip


3. Nebula uses the built-in Android (Google) voice recognition classes to convert speech-to-text for voice control.

4. Nebula uses a Google search of latitude, longitude for the WhereIs command.