Tutorials and documentation

Resources for Sosk users

Getting Started

Sosk consists of several parts.

  • an active tenant on Sosk SaaS platform
  • the probes spread across your network
Let's see how to bring this up.

Create your tenant

When you apply for a Sosk account we automatically create a private tenant just for you and your data. Your tenant is referred as your "zone" and has a unique ID. For example you may obtain the "zone51" if you are lucky enough.

Just use Sosk account creation form to apply for your private tenant. You just need to provide a valid mail address and a chosen password. Feel free to provide the optional informations as it allows us to better know our customers. However none of them are mandatory.

Right after your account creation you can use the login form to sign in. You will be directed to your tenant wgere demo data have been published. You can then see active probes and demonstration dashboards.

Switch your tenant to production state

To be able to register your own probes and to change settings you will need to switch your tenant mode to "production state". This operation is manually done during Beta phase. Just contact Sosk support by mentionning your account email and the zone you want to enable. Et voila !

Your tenant is ready, you can setup your probes

Setup a probe for Sosk

Sosk probes can be setup on several platforms.

  • Raspberry Pi (recommended)
  • Pi alternatives like Banana Pi etc
  • Virtual machines armhf (x86 soon)
You may find useful to launch small VPS instance or cheap ARM server from various Cloud hosting companies like OVH, Scaleway, AWS, GCE, Vultr and so on. Prices are as low as 2.5€ / month.

For now we will cover the well known Raspberry Pi setup. Future docs will allow you to setup Pi Zero, or Wireless Pi etc.

Pre-requisites

You will need
  • A Raspberry Pi v2 or v3
  • A micro SD card (min. 2Gb)
  • Sosk ISO image (MD5)
  • A micro SD card reader
  • A power adapter
  • A small USB stick

Setup the probe

Flash image

Flash the Sosk ISO image to your SD card. No need to expand the filesystem or to change partition logic. Optionaly you may check the MD5/SHA1 checksum of the SD card right after flahsing to ensure all is correct.

Enable enrollment on your zone

In your management interface, go to "Zone settings" and switch the "Probe enrollment" setting to ON. It will allows probes to join your zone for the next 1 hour, 1 day or forever (bad idea !). Choose a private value for your PSK, or let Sosk generate one for you.

Prepare the USB stick

Plug in your USB stick, create a directory exactly named "sonar" at the root. Create a text file exactly named "config.yaml" in it, and put the following content in. Replace zone2 by your zone name (example: zone51) and the zone PSK by your PSK. Be very careful, every space, tab or dash is important. The hostname of the probe will be randomly generated, this is the recommended way. Other parameters could be provided within the YAML file, check the network configuration guide if you need to change anything.

---
probesetup::myhostname: RANDOM
probesetup::myzone: zone2
probesetup::zonepsk: YOUR_ZONE_PSK_HERE
probesetup::mastername: master.sonar.acipia.net
      					

Boot the Pi

Just plug the Raspberry Pi to a DHCP-enabled network. It should be up within 2 minutes.

Plug the USB stick

Now plug the USB stick we've setup previously. This step may take up to 5 minutes depending of the Internet available bandwidth. Your probe needs to download several packages then register unt your zone. During this time feel free to open the "event log" panel in your Management interface, and go take some coffee, you deserve it.

Check the registration

Your newly enrolled probe should have appeared in the "probes" panel in your Management interface, with a "in-sync" status. You can unplug the USB stick and keep it for further enrollments. Congratulations !

FAQ

What about Raspberry Pi 1A 1B etc ?

These models with less than 1Gb RAM are not powerful enough.

How to flash SD card with ISO file ?

Just use dd (Linux & MacOS) or Win32DiskImager (Windows) to flash your SD card with the provided image. In cas you need further instructions you can refer to Raspberry Pi documentations.

What to do if it doesn't work ?

Check the "event logs" pane and double-check you've entered the right PSK. You may also contact support..

What does the image contain ?

The image contains just a Raspbian OS, which is a Debian-based Linux distribution customized for Raspberry Pi. Sosk version differs only by adding Puppet agent package and some bootstrap logic specific to Sosk usage.

Under which license is this OS distributed ?

Sosk image is just a Raspbian Jessie image with additional packages like Puppet. These packages are free software, the exact distribution terms for each program are described in the individual files in /usr/share/doc/*/copyright. You may contact us if you feel we forgot to provide the source code of modified opensource software. For more details see our FLOSS testimony.

Network configuration (optional)

What can be changed

Before enrollement, or during probe's life, you may need to adjust some local network settings on each probe. It will be needed to switch a probe to wireless mode, or to use a proxy server, or to use a statuc IP address instead of DHCP.
We will see how to adjust hte following settings :

  • sosk.io master name (and port)
  • dhcp mode
  • static ip addressing
  • switch to wireless mode
  • dns servers to use
  • http proxy (and port)

USB key setup

You will need a classic USB key, with a partition formatted in FAT32 or NTFS. If you don't know what it means, this is a good thing as the majority of USB sticks are used this way.
Follow these steps :

  • Create a "sonar" directory at the very top level of the key
  • Create a "config.yaml" file in this directory
  • Edit the YAML file and make it suits to your needs (see below)

YAML config file

The YAML file (config.yaml) is just a text file with parameters. Always check your syntax with a tool like YAMLchecker.com to ensure your file is correctly formatted. With YAML the indentation (space before text) allows to specify hierarchy (like root > ethernet interface > ip address). So be sure to copy / paste the following example before changing it according yo your needs. You can group several examples together or ignore some. If no value is provided, default value will be used (ie no proxy setting means there is no proxy to use).

Header of the file

The top of the file will always show a YAML header (---) followed by the 3 only mandatory parameters : zone master, zone id and zone psk. However these parameters will only be in use in case of an enrollment. If your probe is already enrolled, you can leave the default values. The name of your "master server" depends on your local reseller and service level.

---
probesetup::myzone: zone51
probesetup::zonepsk: YOUR_ZONE_PSK_HERE
probesetup::mastername: master.sonar.acipia.net
                     
These values should only be changed if you need to enroll the probe, for the first time or another time.

Proxy settings

probesetup::puppet_proxy_host: proxy.lan
probesetup::puppet_proxy_port: 3128
      					

Network settings

probesetup::interfaces:
 eth0:
   mode: static
   address: 10.20.30.47
   netmask: 255.255.255.0
   gateway: 10.20.30.254
   dns-nameservers: 10.100.1.5 10.100.1.6
                     
"mode" parameter could take "dhcp" as a value while you may still specify some dns server(s). DHCP mode on Ethernet wired interface is the default configuration in case no parameter is provided.

Wireless settings

probesetup::interfaces:
 wlan0:
   mode: dhcp
   wpa-ssid: my-local-ssid
   wpa-psk: ThisIsSoSecret
      					
You can combine Wireless settings with "static" ip mode. However try to avoid such complex network setup as you will have to manually setup each probes again in case of a change.

Full example

Say you need to setup a probe with a static IP address on Ethernet port, and to make use of a internal proxy server to reach the Internet. Your YAML will look like following.

---
# common header
probesetup::myzone: zone51
probesetup::zonepsk: DOES-NOT-MATTER
probesetup::mastername: master.sonar.acipia.net<

# proxy settings
probesetup::puppet_proxy_host: mysquid.lan
probesetup::puppet_proxy_port: 8080

# IP settings
probesetup::interfaces:
  eth0:
    mode: static
    address: 10.20.30.47
    netmask: 255.255.255.0
    gateway: 10.20.30.254
    dns-nameservers: 10.100.1.5

USB key usage

Now that your key is ready we will use it to make things happen on the probe.
Follow these steps :

  • Ensure that the probe is powered on (red led fixed on)
  • Be sure that the probe is linked over the network (for wired mode)
  • Plug your USB stick to the probe
  • Wait 3-4 minutes
  • Check that the probe is showing up in your management interface
  • Unplug the USB key
  • If it didnt work you may find logfiles on your USB key

Menu 5

veritatis et quasi architecto beaasi architecto beatae v veritatis et quasi architecto beaplicabo.