2.4. Automate UserGate Deployment Using Cloud-init

Cloud-init is an industry standard for cross-platform VM instance initialization in clouds of different providers. UserGate supports initial configuration using the cloud-init mechanism. UserGate setup is done using two modules:

  • UserGate setup using CLI (file with a #utm-config header). All CLI commands can be used for full instance setup.

  • License activation (file with a #utm-license header).

No other cloud-init modules are supported.

Example configuration file with CLI commands (user-data):

#utm-config 
#set password for initial Administrator (Admin). Obligatory command. 
password 123 
#Set addresses and settings for network interfaces: 
set network interface adapter port1 \ 
ip-addresses [ 172.16.6.9/24 ] \ 
enabled on \ 
zone "Trusted" 
set network interface adapter port2 \ 
ip-addresses [ 172.16.8.9/24 ] \ 
enabled on \ 
zone "Untrusted" 
set network interface adapter port3 \ 
ip-addresses [ 172.16.7.9/24 ] \ 
enabled on \ 
zone "DMZ" 
#Create network gateway to Internet: 
create network gateway \ 
ip 172.16.8.2 \ 
default on \ 
interface port2 \ 
virtual-router default \ 
enabled on 
#Create firewall rule to allow traffic from Trusted to untrusted security zones: 
create network-policy firewall \ 
position 1 upl-rule ALLOW \ 
src.zone = Trusted \ 
dst.zone = Untrusted \ 
enabled(true) \ 
name("Cloud-Init: Allow from Trusted to Untrusted")

All CLI commands available to the administrator can be used in this file. For more details on CLI commands, see the chapter Command Line Interface (CLI).

# marks the beginning of a comment, and a backslash (\) denotes a wrap to the next line.

If you need to activate the instance being created, you can do so by specifying the licensing parameters in a separate file. Note that activation is only possible if the instance has Internet access. Example license activation file (vendor-data):

#utm-license
pin_code: UGN4-XXXX-YYYY-ZZZZ-AAAA
reg_name: UG-test
email: email@company.com

user_name: Steven
last_name: Taylor
company: UserGate
country: UAE
region: Dubai

The two files can be merged into one using the multipart format:

Content-Type: multipart/mixed; boundary="//"
MIME-Version: 1.0 
--// 
Content-Type: text/utm-config; charset="utf-8" 
MIME-Version: 1.0 
Content-Transfer-Encoding: 7bit 
Content-Disposition: attachment; filename="config.txt" 
#utm-config 
password 123 
set network interface adapter port1 \ 
ip-addresses [ 172.16.6.9/24 ] \ 
enabled on \ 
zone "Trusted" 
set network interface adapter port2 \ 
ip-addresses [ 172.16.8.9/24 ] \ 
enabled on \ 
zone "Untrusted" 
set network interface adapter port3 \ 
ip-addresses [ 172.16.7.9/24 ] \ 
enabled on \ 
zone "DMZ" 
create network gateway \ 
ip 172.16.8.2 \ 
default on \ 
interface port2 \ 
virtual-router default \ 
enabled on 
create network-policy firewall \ 
position 1 upl-rule ALLOW \ 
src.zone = Trusted \ 
dst.zone = Untrusted \ 
enabled(true) \ 
name("Cloud-Init: Allow from Trusted to Untrusted") 
--// 
Content-Type: text/utm-license; charset="utf-8" 
MIME-Version: 1.0 
Content-Transfer-Encoding: 7bit 
Content-Disposition: attachment; 
filename="license.txt" 
#utm-license 
pin_code: UGN4-XXXX-YYYY-ZZZZ-AAAA r
eg_name: UG-test 
email: email@company.com 

user_name: Steven 
last_name: Taylor 
company: UserGate 
country: UAE 
region: Dubai 
--//

Settings can be transferred to the UserGate device:

  1. Using the methods implemented by the cloud provider - e.g., when creating a VM (droplet) on Digital Ocean, settings should be added to the optional field User data (Select additional options --> User data). Other cloud services providers support similar methods of settings transfer.

  2. Using a mounted .iso image. The image must contain files named meta-data, user-data, and vendor-data with the following contents:

meta-data:

instance-id: vm1

user-data - with CLI instance setup commands:

#utm-config 
#set password for initial Administrator (Admin). Obligatory command. 
password 123 
#Set addresses and settings for network interfaces: 
set network interface adapter port1 \ 
ip-addresses [ 172.16.6.9/24 ] \ 
enabled on \ 
zone "Trusted" 
...

vendor-data - with optional licensing information:

#utm-license 
pin_code: UGN4-XXXX-YYYY-ZZZZ-AAAA 
reg_name: UG-test 
email: email@company.com 
...

To create an .iso image in Linux, you can use the mkisofs utility as follows:

mkisofs -joliet -rock -volid "cidata" -output nocloud.iso meta-data user-data vendor-data

Mount the resulting .iso image on the UserGate VM. After the first successful boot, the VM will receive all settings specified for it in the created files.