Using templates to configure services

Note The tool is under construction.

Contents

Introduction
Template profile
- Properties of the copied parameters
  - available
  - block
  - default
  - description
  - name
  - separate
- Example: OpenVPN parameters profile

Introduction

This manual explains how to configure services with templates. Simply use the templates to create multiple-use configuration profiles for the cl-setup tool.

Conventions:

Services are settings of a package or packages, combined in a logical solution.
Profiles are sets of templates used to configure a service.

Imagine that you want to create a kernel profile, containing your customized kernel settings. You only need to perform three actions subsequently:

1) Create a file named /var/calculate/ini.env and add the following line to it:

[setup-kernel]
setup.name = Kernel settings

Now cl-setup can recognize the setup profile you submitted and handle it:

# cl-setup list
...
kernel - Kernel settings

2) You can now prepare a template for kernel settings. Use the same tool to set the path to your templates:

# cl-setup setup kernel

Basic path and templates will be created.

3) Now create the template:

vi /var/calculate/templates/setup/kernel/sysctl.conf
# Calculate format=procmail path=/etc mergepkg(sys-apps/baselayout)!=
net.ipv4.ip_forward = 1

where:

# Calculate is the template header;
format=procmail is the configuration file format. It must be specified so that your template updates the settings without overwriting the whole file;
path=/etc is the path to the configuration file;
mergepkg(sys-apps/baselayout)!= is a function for parallel checkup of the package for which the settings are being implemented and fixes of the files that are being created. It is anchored at the package manager level, so that the files you created could be deleted if the package is removed.

Done! Now, you only have to execute the following command to launch kernel configuration:

cl-setup kernel

Once this operation is completed, the package forwarding setup variable in /etc/sysctl.conf will get a new value, while the file header will be modified to contain the path to your template:

#------------------------------------------------------------------------------
# Modified Calculate Utilities 3.5.9
# Processed template files:
# /var/calculate/templates/setup/kernel/sysctl.conf
# For modify this file, create /etc/sysctl.conf.clt template.
#------------------------------------------------------------------------------
...
net.ipv4.ip_forward = 1

In addition, a record will be added to /etc/calulate/ini.env at runtime, containing the execution time stamp:

[setup-kernel]
run = Mon, 08 Jan 2018 02:14:36 +0300

This entry will tell the utilities that the kernel service has been configured and will use your template to generate sysctl.conf when reinstalling the package.

This example describes a simple way of using template. Below we will explain how to pass parameters to your templates via the cl-setup tool, to check input values or to do even more complex settings. Add your templates to a LiveUSB or to your profile to always have access to your preferred administration tools.

Template profile

cl-setup had the following syntax:

cl_setup [profile] [option or option=value (space separated if more than one]

To retrieve the list of available profiles, run:

# cl-setup list
openvpn - Настройка OpenVPN

Template profiles, copied parameters and conditionals are described in the ini.env. file. You can choose any available path to custom configuration file: in /var/calculate/ini.env, /var/calculate/remote/ini.env, /etc/calculate/ini.env , or else in your profile.

To add a profile, create a "setup-service_name" section in ini.env, for example:

[setup-openvpn]

Properties of the copied parameters

In the Service Settings section, specify all available parameters, listing their properties in the same order in which they will be displayed when calling the help page:

cl-setup help service_name

The properties are comma-separated, and followed by the value. Example:

dns.name = DNS

Available properties:

available

Here you can describe the possible values the parameter takes. In square brackets, you can list the allowed values. Use comma-separated values in round brackets for multiple choice and curly brackets for a specific type of value, such as an IP-address. Example:

remote.available = [a-zA-Z0-9_-\.]

When you choose between on and off, the "checkbox" field will be displayed in the GUI client window. Example:

gateway.available = (on, off)

block

This function prevents from using parameters that block each other, while making it impossible to select a parameter for a specific value of another one. In this case, the value must be specified in curly braces. You may specify multiple conditions, comma-separated. Example:

dns.block = type(client)

default

This is the default field value. If the user does not specify a parameter, it will be filled with this default.

type.default = client

description

Brief description of the settings It is provided when help is displayed for the settings profile To localize, put the locale in brackets at the end of the line.

name

Parameter name in English To localize, put the locale in brackets at the end of the line. If you choose to localize, the English locale is also mandatory. Example:

name.name[fr] = Option

separate

Description of the parameter block starting with this element. As well as the parameter name, it can be localized. Example:

type.separate[fr] = Options générales

Example: OpenVPN parameters profile

See below a sample OpenVPN configuration service:

[setup-openvpn]
setup.name = OpenVPN settings
setup.description = ...
setup.description[ru] = ...
setup.name[ru] = Настройка OpenVPN
type.available = (client, server)
type.default = client
type.name = Type
type.name[ru] = Тип
type.separate = Default options
type.separate[ru] = Общие настройки
name.available = [a-zA-Z0-9_-]
name.name = Key name
name.name[ru] = Имя ключа
easy-rsa.name = path to directory easy-rsa
easy-rsa.name[ru] = путь к директории easy-rsa
easy-rsa.default = /usr/share/easy-rsa
gateway.available = (on, off)
gateway.block = type(client)
gateway.name = Default gateway
gateway.name[ru] = Маршрут по умолчанию
gateway.separate = Server setup
gateway.separate[ru] = Настройки сервера
dns.available = {ip}
dns.block = type(client)
dns.name = DNS
remote.available = [a-zA-Z0-9_-\.]
remote.block = type(server)
remote.name = Server address
remote.name[ru] = Адрес сервера
remote.separate = Client settings
remote.separate[ru] = Настройки клиента
port.available = [0-9]{4,5}
port.block = type(server)
port.default = 1194
port.name = Port
port.name[ru] = Порт