Improve this doc
Network Setup on

Network Setup

Introduction

In order to deploy code to your device(s), they will need to be connected to the internet in some shape or form. The balena HostOS manages your devices' network connection with ConnMan, an open source connection manager.

Currently all balena devices are configured to favour ethernet and will automatically use this connection type if it is available. You can define all manner of network configurations using Connman, for example setting a static IP.

Network Requirements

In order for a balena device to get outside of the local network and connect to the balena API, there are a few core network requirements.

Balena makes use of the following ports:

  • 443 TCP - This is the most fundamental requirement - it is used to connect to the VPN and the web terminal, and many web endpoints using TLS (https://.)
  • 123 UDP - For NTP time synchronisation.
  • 53 UDP - For DNS name resolution.

Each of these should work with outward only (and inward once outward connection established) firewall settings.

Additionally, you should whitelist the following domains for the relevant ports above:

  • *.balena-cloud.com
  • *.docker.com
  • *.docker.io

Additionally, an outgoing connection to mixpanel.com is made. This is not a functional requirement for balena, but allows tracking of some useful metrics.

Ethernet Connections

As mentioned earlier, balena the host OS defaults to using ethernet for internet connectivity, so if you connect an active ethernet cable to your device and all the network requirements are satisfied, your device should simply just connect to the dashboard and you should be able to push code to it.

If this this is not the case, and your device is still not online 10 minutes after power up, then give us a shout on the forums.

Set Static IP

In order to configure static IP on a pre-provisioned SD card perform the following steps:-

  • Mount the FAT partitions of the OS image either directly from the .img file, or by burning the SD card and mounting it on your computer. The volume will be called resin-boot.
  • Inside the resin-boot partition you will find a config.json file and in it you will see a network key/value pair which contains JSON string encoded Connman settings. Now edit the value to include the following entry, replacing <static IP> with your desired static IP:-

NOTE: Before Resin OS 1.2, the resin-conf partition was used instead of resin-boot.

[service_home_ethernet]
Type = ethernet
IPv4 = <static IP>/255.255.255.0/192.168.1.1
Nameservers = 192.168.1.1,8.8.8.8

Note: This assumes your network gateway/router is 192.168.1.1 and your DNS is 192.168.1.1,8.8.8.8. Both of these can and will vary, so adjust this according to your local network configuration.

The image will now contain your static IP configuration, simply write it to your SD card as you usually would. If you're curious about further configurability, this network.config file is simply a Connman network configuration file (see here and here). The Connman Docs have more details on other configuration options.

WiFi Connections

To connect your devices to a WiFi network select the wifi option, put in your network's SSID and, if the network is encrypted, enter a passphrase.

Wifi Settings

NOTE: The device will automatically determine your network's encryption (if any) and connect using the provided passphrase, there's no need to specify the encryption type.

Multiple WiFi Connections

Though we currently don't support multiple WiFi SSIDs through the user interface, this can be achieved by manually editing the config.json file on your SD card. To add a second WiFi network to the configuration simply append the following to "network/network.config"::

"files": {
    "network/settings": "[global]\nOfflineMode=false\n\n[WiFi]\nEnable=true\nTethering=false\n\n[Wired]\nEnable=true\nTethering=false\n\n[Bluetooth]\nEnable=true\nTethering=false",
    "network/network.config": "[service_home_ethernet]\nType = ethernet\nNameservers = 8.8.8.8,8.8.4.4\n\n[service_home_wifi]\nType = wifi\nName = My_Wifi_Ssid\nPassphrase = my super secret WiFi passphrase\nNameservers = 8.8.8.8,8.8.4.4\n\n[service_office_wifi]\nType = wifi\nName = My_2nd_Wifi_Ssid\nPassphrase = my super secret password\nNameservers = 8.8.8.8,8.8.4.4"
  }

In general the network config follows the ConnMan configuration file format, so you can configure your network in anyway connMan allows. Follow the official guide for details of how to configure your network if you have more complicated requirements than the our standard configuration.

Changing your Network Configuration

On all devices excluding the Intel Edison, it is possible to change your WiFi SSID or Passphrase after downloading the .img.

Using the CLI

The best way to do this is using the balena CLI. Install the CLI, plug your SD Card into your computer and run the following command, passing the correct device type associated with your image.

Example for reconfiguring a Raspberry Pi image:

$ sudo balena config reconfigure --type raspberry-pi

The command will ask a simple questions and will update the config.json file for you. You can also edit advanced settings by passing the --advanced flag.

$ sudo balena config reconfigure --type raspberry-pi --advanced

To view an images current configuration run:

$ sudo balena config read --type raspberry-pi

If you'd like to reconfigure the image's network settings in an automated way you can use balena config write.

Manually Editing Config.json

Currently this can be done by editing the config.json. This file can be found in a partition called resin-boot on the SD card for most devices (on Resin OS versions before 1.2 it was resin-conf or flash-conf), except the Intel Edison. For the Intel Edison it can be found in in resin-conf once you have mounted the config.img.

Note: For the Beaglebone, VIA VAB-820, Intel NUC and the Intel Edison, you can only change the WiFi configuration before you provision the device. Since these devices rely on burning the OS to internal media such as eMMC, trying to change these settings after provisioning will have no effect, you will need to reprovision the device.

In the config.json file you will need to edit the section called files with whatever SSID and passphrase you require.

"files": {
    "network/settings": "[global]\nOfflineMode=false\n\n[WiFi]\nEnable=true\nTethering=false\n\n[Wired]\nEnable=true\nTethering=false\n\n[Bluetooth]\nEnable=true\nTethering=false",
    "network/network.config": "[service_home_ethernet]\nType = ethernet\nNameservers = 8.8.8.8,8.8.4.4\n\n[service_home_wifi]\nType = wifi\nName = My_Wifi_Ssid\nPassphrase = my super secret WiFi passphrase\nNameservers = 8.8.8.8,8.8.4.4"
  }

Note: Unfortunately this file is not nicely formatted and it requires that you use the \n to signify a newline.

3G or Cellular Connections

Currently 3G or Cellular modems are not supported out of the box, but they are easily setup on a balena device. During the setup of your cellular connection, you will need an ethernet or WiFi connection to the device so that it can correctly provision and download a container with the necessary configurations.

To get started with a cellular connection have a look at our blog post "A guide to cellular connectivity on balena devices" and the corresponding github repository.

Captive Portal Network Setup

In some cases devices will need to be provisioned and sent out to sites where the exact network or WiFi configuration is unknown. In these circumstances its often nice for a device to serve up an captive portal which allows an onsite user to configure the WiFi for a device.

If you require this functionality in your devices, you should have a look at our captive portal project called WiFi Connect and its associated blog post

Troubleshooting

If you have issues connecting with the WiFi device, first check to ensure the SSID and passphrase are correct. If they are, try rebooting with an ethernet cable plugged in, then booting again with just WiFi.

If neither of these approaches work, ask us some questions on the forums!