How to setup a simple cloud-init environment for testing

Last modified on 30 Nov, 2020. Revision 25

Before deploying Clavister NetWall in a cloud-init environment it could be handy to have a test environment for developing the provisioning scripts.

Cloud-Init operation overview
Setting up pre-requisites
- Setting up the DHCP Server
- Setting up the HTTP Server
Verifying that the environment works
Example datasource files
Successful boot
Related articles

Up to date for	cOS Core 13.00.08
Supported since	cOS Core 13.00.08
Status	OK

Cloud-Init operation overview

The cloud-init system process will attempt to configure a cOS Core VM by using information that is going to be retrieved using HTTP from a central online repository available on 169.254.169.254. This repository can be a simple web server or part of a more complex setup using an orchestration system like OpenStack.

In order for the process to work correctly the following pre-requisites are needed:

DHCP server capable of supporting option 121, with leases that contain route information to reach 169.254.169.254
Web server or equivalent setup that can provide the needed files for configuration. These files need to be accessible in the /openstack/2015-10-15/ path.
Network infrastructure allowing at least one VM interface to receive the DHCP lease and reach 169.254.169.254.

Setting up pre-requisites

Setting up the DHCP Server

The DHCP server need to supply a route for cOS Core to reach 169.254.169.254, the internal DHCP Server in Clavister NetWall can be used to achieve this, on the DHCP Scope that will supply IPs to the VM add custom option where code is 121, type is binary and parameter is the route in HEX to be added, example below:

The routing parameter is in the following format, {prefix_length}{destination_prefix}{router}, below is an example how to calculate the static route for 169.254.169.254/32 using the router 192.168.12.1 which equals 20A9FEA9FEC0A80C01.

Decimal	Hex	Comment
32	20	Prefix Length
169	A9	Destination Prefix
254	FE
169	A9
254	FE
192	C0	Router
168	A8
12	0C
1	01

Setting up the HTTP Server

Simplest possible is to use a Linux host behind the same Clavister NetWall that is providing DHCP, create a SAT rule for 169.254.169.254 and send the traffic to a Linux server on for example port 8001.

Prepare an environment by creating the following directory structure and placeholder files somewhere on the filesystem

Folder Structure

user@server:~# mkdir cloud-init-labb
user@server:~# cd cloud-init-labb
user@server:~/cloud-init-labb# mkdir openstack
user@server:~/cloud-init-labb# mkdir openstack/2015-10-15
user@server:~/cloud-init-labb/openstack/2015-10-15# cd openstack/2015-10-15
user@server:~/cloud-init-labb/openstack/2015-10-15# touch network_data.json meta_data.json user_data

Then start the a simple HTTP Server by issuing the following command:

Start HTTP Server

user@server:~# cd cloud-init-labb
user@server:~/cloud-init-labb# python3 -m http.server 8001
Serving HTTP on 0.0.0.0 port 8001 (http://0.0.0.0:8001/) ...

Verifying that the environment works

Import the cOS Core image into the virtual environment and boot up, if all the pre-requisites are setup correctly the following should be seen on the Linux host

HTTP Server Output

user@server:~/cloud-init-labb# python3 -m http.server 8001
Serving HTTP on 0.0.0.0 port 8001 (http://0.0.0.0:8001/) ...
192.168.12.106 - - [27/Nov/2020 17:25:03] "GET /openstack/2015-10-15/network_data.json HTTP/1.0" 200 -
192.168.12.106 - - [27/Nov/2020 17:25:03] "GET /openstack/2015-10-15/meta_data.json HTTP/1.0" 200 -
192.168.12.106 - - [27/Nov/2020 17:25:03] "GET /openstack/2015-10-15/user_data HTTP/1.0" 200 -

In the console of the virtual machine you should see the following output, as the files are still empty the cloud-init process will fail with an error:

cOS Core CLI Output

Clavister cOS Core 13.00.08.03-35596 DEMO 
Copyright Clavister 1996-2020. All rights reserved
QuickSec 3.2.0

Build : Nov 10 2020



Interfaces:
If1             IPAddr 192.168.0.228    HwAddr 00-0C-29-C8-4C-73
  Builtin e1000 - 82545EM Gigabit Ethernet Controller (Copper)  Bus 2 Slot 0 Port 0 IRQ 11
If2             IPAddr 192.168.12.106   HwAddr 00-0C-29-C8-4C-7D
  Builtin e1000 - 82545EM Gigabit Ethernet Controller (Copper)  Bus 2 Slot 1 Port 0 IRQ 10
If3             IPAddr 0.0.0.0          HwAddr 00-0C-29-C8-4C-87
  Builtin e1000 - 82545EM Gigabit Ethernet Controller (Copper)  Bus 2 Slot 2 Port 0 IRQ 9


Previous event: 2020-11-27 17:30:24: Updating DHCP configuration

System running

Device:/> Cloud init - Connecting to server 169.254.169.254:80
[Connected to 169.254.169.254:80]
[Received 190 bytes from 169.254.169.254:80]
[Closing connection to 169.254.169.254:80...]
[6][Connection to 169.254.169.254:80 closed. (Normal close)]
[INFO] No network data found in received file. Will use default configuration.
Cloud init - Connecting to server 169.254.169.254:80
[Connected to 169.254.169.254:80]
[Received 190 bytes from 169.254.169.254:80]
[Closing connection to 169.254.169.254:80...]
[7][Connection to 169.254.169.254:80 closed. (Normal close)]
[INFO] No meta data found in received file (wrong json format?).
Cloud init - Connecting to server 169.254.169.254:80
[Connected to 169.254.169.254:80]
[Received 198 bytes from 169.254.169.254:80]
[Closing connection to 169.254.169.254:80...]
[6][Connection to 169.254.169.254:80 closed. (Normal close)]
[INFO] No user data found in received file, #cli-config not found (wrong format?).
[ERROR] There are errors in the received configuration.
Please check 'Diagnostic Console', (or try to manually activate the changes that passed verification).


Device:/> 

Example datasource files

Below are some example of format and example files that can be used as basis for customisation of a virtual Clavister NetWall

network_map.json

The file network_map.json is used to configure and setup any network related configuration of cOS Core, if the default values on cOS Core are OK this file can be left empty.

network_map.json - Format

{
  "services": [
    {
      "type": "dns",
      "address": "123.123.123.123"
    },
    {
      "type": "dns",
      "address": "123.123.123.124"
    }
  ],
  "networks": [
    {
      "network_id": "some_id_1",
      "type": "ipv4_dhcp",
      "link": "some_link",
      "id": "network1"
    },
    {
      "network_id": "some_id_2",
      "type": "ipv4",
      "link": "some_link2",
      "id": "network2"
      "ip_address":"FFFF:0000:ABCD:0000:0300:0123:0123:0123",
      "netmask":"ffff:ffff:ffff:ffff:ffff:0:0:0"
    },
     {
      "network_id": "some_id_3",
      "type": "ipv4",
      "link": "some_link2",
      "id": "network2_ip4",
      "ip_address":"123.123.123.123",
      "netmask":"255.255.255.0"
    }
  ],
  "links": [
    {
      "type": "ovs",
      "vif_id": "some_vif_id",
      "ethernet_mac_address": "aa:aa:aa:aa:aa:aa",
      "id": "some_link",
      "mtu": 1500
    },
    {
      "type": "ovs",
      "vif_id": "some_vif_id_2",
      "ethernet_mac_address": "bb:bb:bb:bb:bb:bb",
      "id": "some_link2",
      "mtu": 1500
    }
  ]
}

The example below renames the interfaces to wan, mgmt and lan, set wan and mgmt to use DHCP and a static IP on lan.

network_map.json - Example

{
  "networks": [
    {
      "network_id": "wan", 
      "type": "ipv4_dhcp", 
      "link": "wan", 
      "id": "network_dhcp"
    },
    {
      "network_id": "mgmt", 
      "type": "ipv4_dhcp", 
      "link": "mgmt", 
      "id": "mgmt_net"
    },
    {
      "network_id": "lan", 
      "type": "ipv4", 
      "link": "lan", 
      "id": "lan_net", 
      "ip_address":"192.168.50.1",
      "netmask":"255.255.255.0"
    }
  ], 
  "links": [
    {
      "type": "ovs", 
      "vif_id": "96fffdf6-8c26-4de6-8f42-ad57501447da", 
      "ethernet_mac_address": "00:0C:29:C8:4C:73", 
      "id": "wan", 
      "mtu": 1500
    },
    {
      "type": "ovs", 
      "vif_id": "96fffdf6-8c26-4de6-8f42-ad57501447da", 
      "ethernet_mac_address": "00:0C:29:C8:4C:7D", 
      "id": "mgmt", 
      "mtu": 1500
    },
    {
      "type": "ovs", 
      "vif_id": "reg_link", 
      "ethernet_mac_address": "00:0C:29:C8:4C-87", 
      "mtu": 1500,
      "id": "lan" 
    }
  ]
}

meta_data.json

The file meta_data.json is used to configure device name, admin password, ssh keys for admin user (if needed) and can’t be left empty

meta_data.json - Format

{
  "name": "MyDevice",
  "admin_pass": "aStrongPassword121!@",
  "public_keys":
    {
       "firstkey": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAQEAsn...",
       "secondkey": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAQEAl6..."
    }
}

Below is a minimal meta_data.json that sets a password and name for the device.

meta_data.json - Example

{
  "name": "MyDevice",
  "admin_pass": "aStrongPassword121!@"
}

user_data

The file user_data has no extension, and is expected to contain one CLI script with further configuration. The tag ‘#cli-config’ is expected to mark the beginning of the CLI script commands, if no commands are needed, a user_data with only #cli-config is needed:

user_data - Format

#cli-config

Below is an example on how to prepare a gateway for addition into InControl, including enabling default gateway on wan and mgmt, moves mgmt to it’s own PBR and enables management on the mgmt interface. It also enables a DHCP server on the lan interface.

user_data - Example

#cli-config
add PSK netcon_key Type=HEX PSKHex=2a02917cf27aec1e5235e0345ae046c2af4cf9eb7413390a9aa2b29ffe961435c0aab279073031d7d8e4528174b4ea1e5abef3d688c5f9599ee526aa2ac6b4e6
add Address FQDNAddress incontrol Address=incontrol.domain.tld
add RemoteManagement RemoteMgmtNetcon Interface=any Key=netcon_key Network=all-nets Type=DeviceInitiated InControlIP=incontrol RemoteManagementID=MyDevice
set Interface Ethernet wan AutoDefaultGatewayRoute=Yes
set Interface Ethernet mgmt AutoDefaultGatewayRoute=Yes
add Address IP4Address lan_dhcp_pool Address=192.168.50.100-192.168.50.200
add DHCPServer dhcp_lan Interface=lan IPAddressPool=lan_dhcp_pool DefaultGateway=InterfaceAddresses/lan_ip DNS1=InterfaceAddresses/lan_dns1 DNS2=InterfaceAddresses/lan_dns2
add IPPolicy DestinationInterface=wan DestinationNetwork=all-nets SourceInterface=lan SourceNetwork=InterfaceAddresses/lan_net Service=dns-all Name=DNS
add RoutingTable mgmt Ordering=Only 
set Interface Ethernet mgmt MemberOfRoutingTable=Specific RoutingTable=mgmt
set RemoteManagement RemoteMgmtHTTP HTTP_If1 Interface=mgmt Network=all-nets name=HTTP
set RemoteManagement RemoteMgmtSSH SSH_If1 Interface=mgmt Network=all-nets Name=SSH

Successful boot

Below is an example for a successful boot of cOS Core using the example files above.