06 | 07 | 2020

Структура пакетов

Что такое Packages в PFSense

Пакеты в pfSense – это дополнения, устанавливаемые в систему, и позволяющие расширить ее функциональность. Как и все в pfSense, управление пакетами осуществляется с помощью WEB интерфейса. Пакеты могут включать в себя обычные приложения FreeBSD, скрипты или просто дополнительные модули управления системой.

Все настройки пакета хранятся в едином конфигурационном XML файле pfSense, который может быть сохранен или восстановлен через стандартные операции WEB интерфейса. Каждый раз при загрузке системы и при сохранении настроек пакета происходит формирование новых конфигурационных файлов приложений, входящих в состав пакета.

 

Замечание:

В FreeBSD специальным образом оформленные приложения носят название порт (port) или пакет (package). Но для отличия от пакетов pfSense все программы FreeBSD будет далее называться, как ‘приложение’.

Пакеты pfSense обычно состоят из следующих элементов:

Наименование файла Описание
Файл Манифеста (manifest)
Конфигурационный XML файл, содержащий информацию обо всех доступных для установки пакетах. Обычно он расположен на портале pfSense: 
Локальный кэш /tmp/pkg_info.cache
Конфигурационные файлы пакета pfSense
Один основной и несколько дополнительных XML файлов, содержащих информацию о конфигурации пакета pfSense.
Каталог с файлами /usr/local/pkg/
Библиотека php функций пакета pfSense
В файлах с расширением .incсодержатся php функции, используемые для управления пакетом pfSense.
Каталог с файлами /usr/local/pkg/
Приложения FreeBSD или скрипты Стандартные приложение FreeBSD или скрипты системы, устанавливаемые из пакетов FreeBSD

 

Что такое Манфест (manifest)

Это конфигурационный  XML файл, содержащий информацию обо всех доступных пакетах для установки pfSense.  Этот файл расположен на портале pfSense.com и используется при обращении клиентов на портал. При удачном соединении клиентская система обновляет у себя локальную копию манифеста с сервера. Если соединение с сервером pfSense.com установить не удалось, то используется текущая локальная копия манифеста.

Структура манифеста:

<?xml version="1.0" encoding="utf-8"?>

<!-- pfSense packages -->
<!-- $Id: pkg_config.7.xml,v 1.121 2008/12/17 01:37:13 mcrane Exp $ -->
<pfsensepkgs>
  <packages>
    <package>
    ...
    </package>
    ...
<ENDOFPACKAGES>
</ENDOFPACKAGES>
    <package>
    ...
    </package>
    ...
  </packages>
</pfsensepkgs>


Манифест состоит из списка пакетов. Информация о каждом пакете содержится в тэге package:

<package>

      <name>Mypkg</name>
      <descr>My test package</descr>
      <category>Test</category>
      <config_file>http://www.pfsense.com/packages/config/mytestpkg.xml</config_file>
      <version>0.1</version>
      <status>ALPHA</status>
      <required_version>1.0</required_version>
   <maintainer> Этот адрес электронной почты защищен от спам-ботов. У вас должен быть включен JavaScript для просмотра. </maintainer>
   <depends_on_package_base_url>
      http://www.pfsense.org/packages/All
   </depends_on_package_base_url>
   <depends_on_package>mypkg1.tbz</depends_on_package>
   <depends_on_package>mypkg2.tbz</depends_on_package>
   <config_file>
      http://www.pfsense.org/packages/config/mypkg/mypkg.xml
   </config_file>
   <configurationfile>mypkg.xml</configurationfile>
   <logging>
      <facilityname>mypkg</facilityname>
      <logfilename>mypkg.log</logfilename>
   </logging>
</package>

 

Описание назначения некоторых тэгов:

Тэг Описание
name, descry, category, version, status, required_version, maintainer Общая информация о пакете, которая отображается в списке доступных пакетов pfSense
depends_on_package_base_url Базовый путь к каталогу инсталляционного пакета.
depends_on_package Имена приложений FreeBSD, которые требуются для пакета и будут установлены вместе с ним.
config_file Ссылка/путь к основному конфигурационному XML файлу пакета вместе с его именем
configurationfile Имя конфигурационного XML файла. (не знаю зачем)
logging Информация о журнале событий (логи) пакета.

 

Такая структура манифеста позволяет создавать сложные пакеты, содержащие несколько приложений FreeBSD (например proxy + antivirus + reports), а также следить за  обновлениями пакетов на портале pfSense. Конфигурационным файлом пакета является основной XML файл, описанный в тэге config_file. В нем должна содержаться дополнительная информация по установке пакета.

  

Конфигурационные XML файлы пакета

Существует как минимум один конфигурационный XML файл пакета. В каждом из таких файлов содержится структура отдельной страницы Web интерфейса пакета и управляющие события по обработке данных формы страницы. Кроме того, основной конфигурационный XML файл содержит дополнительные данные по установке пакета и его конфигурации. Существует два вида страниц Web интерфейса пакета: форма и таблица.

Страница 'форма’ - это обычный диалог редактирования данных. Данные такой страницы хранятся в единственном экземпляре.

Пример страницы-формы Web интерфейса пакета pfSense: 

Страница ‘таблица’ - служит для отображения и управления набором данных. Для добавления или изменения элементов набора данных вызывается страница ‘форма’, конфигурация которой описывается в этом же XML файле. 

Пример страницы ‘таблица’ Web интерфейса pfSense:

 

 

Библиотека PHP функций пакета pfSense

         Это обычный php файл с расширением INC. В нем содержатся все функции по управлению пакетом. Файл должен включаться во все XML файлы пакета, использующие его функции. Минимальный набор функций обычно включает:

  • Управление  установкой пакета
  • Управление  деинсталляции пакета
  • Проверка данных
  • Управление конфигурацией приложений FreeBSD (системных скриптов), входящих в пакет.

 

Структура XML файлов

 

Структура XML файла

 

Конфигурационный XML файл пакета содержит информацию, определяющую каким образом pfSense будет взаимодействовать с пользователем через Web интерфейс и управлять приложением FreeBSD.

 

Структура XML файла пакета

<?xml version="1.0" encoding="utf-8" ?>

<!DOCTYPE packagegui SYSTEM "../schema/packages.dtd">

<?xml-stylesheet type="text/xsl" href="/../xsl/package.xsl"?>

<packagegui>

   <copyright></copyright>

 

   <!-- Package info -->

   <description></description>

   <requirements></requirements>

   <faq></faq>

   <name>mypkg</name>

   <version>1.0.0</version>

   <category>Test</category>

 

   <!-- Link files -->

   <include_file>/usr/local/pkg/mypkg.inc</include_file>

 

   <!-- Page title -->

   <title>Services: My package -> General</title>

 

   <!-- Page operations info -->

   <addedit_string>

      A mytest package has been created/modified.</addedit_string>

   <delete_string>

      A mytest package has been deleted.</delete_string>

 

   <!-- Installation: pfSense GUI menu info -->

   <menu></menu>

 

   <!-- Installation: additional package files info -->

   <additional_files_needed></additional_files_needed>

 

   <!-- Page navigation tabs -->

   <tabs>

      <tab></tab>

   </tabs>

 

   <!-- Page fields -->

   <fields>

      <field></field>

   </fields>

 

 <!-- Page events -->

 <custom_php_validation_command>

 </custom_php_validation_command>

 

 <custom_php_resync_config_command>

 </custom_php_resync_config_command>

 

 <custom_php_install_command>

 </custom_php_install_command>

 

 <custom_php_deinstall_command>

 </custom_php_deinstall_command>

 

</packagegui>

 

TAG description

Содержит описание пакета.

Эта секция присутствует только в основном XMLфайле.

<description>Describe your package here</description>

 

TAG requirements

Cодержит системные требования для пакета.

Эта секция присутствует только в основном XMLфайле.

<requirements>Describe your package requirements here</requirements>

 

TAG faq

Cодержит справочную информацию по пакету.

Эта секция присутствует только в основном XMLфайле.

<faq>Currently there are no FAQ items provided.</faq>

 

TAG name

Cодержит системное имя XMLфайла.

В разделе с этим именем в конфигурации pfSenseсохраняются данные полей текущей страницы пакета.

<name>MyPackage</name>

 

TAG version

Cодержит версию пакета и имеет значение только в основном XMLфайла вашего проекта.В остальных XMLфайлах оно может содержать значение none,к примеру.

<version>1.1.1_1</version>

 

TAG title

Cодержит заголовок текущей страницы Webинтерфейса.

Обычно для этой секции используют формат: Наименование пакета: Название страницы .

<title>Му Package: General settings</title>

 

TAG category

Cодержит информацию о категории, к которой можно отнести пакет.

<category>Test</category>

 

TAG include_file

Cодержит информацию о подключаемых к текущей странице пакета модулях INC.

Обязательно включается INCфайл пакета. Так же могут быть подключены файлы из других пакетов или из системы pfSense, если вы намерены использовать их функции.

<include_file>/usr/local/pkg/mypkg.inc</include_file>

 

TAG menu

Cодержит информацию о пункте меню, связанном с этим пакетом.

Здесь имеются сведения о заголовке, URLи секции меню, где размещается этот пункт.

Эта секция присутствует только в основном XMLфайле и используется при установке пакета.

<menu>

   <name>My package</name>

   <tooltiptext>Modify the MyPackage settings</tooltiptext>

   <section>Services</section>

   <url>/pkg_edit.php?xml=mypkg.xml&amp;id=0</url>

</menu>

 

TAG service

Описывает наименование и опции сервиса.

Эта информация используется системой для управления пакетом.

Эта секция присутствует только в основном XMLфайле и может быть опущена.

<service>

   <name>MyPackage</name>

   <rcfile>mypkg.sh</rcfile>

   <executable>mypkg</executable>

   <description>My Package</description>

</service>

 

TAG tabs

Описывает закладки страниц (tabs) Webинтерфейса пакета.

Эта секция, как правило, одинакова для всех страниц пакета, за исключением элемента active, который обозначает текущую страницу. Элемент urlсодержит ссылку для перехода на страницу.

<tabs>

    <tab>

       <text>General settings</text>

       <url>/pkg_edit.php?xml=mypkg.xml&amp;id=0</url>

       <active/>

    </tab>

    <tab>

       <text>My users</text>

       <url>/pkg_edit.php?xml=mypkg_usr.xml&amp;id=0</url>

    </tab>

</tabs>

Пример Tabs

 

 

TAG additional_files_needed

Cодержит информацию о дополнительных файлах пакета, которые необходимо установить, а так же пути установки и права доступа к ним .

Это должны быть все INCи XMLфайлы пакета (кроме основного), и некоторые другие  файлы, необходимые пакету.

Эта секция

<additional_files_needed>

   <prefix>/usr/local/pkg/</prefix>

   <chmod>0755</chmod>

   <item>

      http://www.pfsense.org/packages/config/mypkg/mypkg.inc

   </item>

</additional_files_needed>

 

TAG adddeleteeditpagefields

Присутствует в странице-таблице, и содержит информацию о колонках таблицы и соответствующих им полях страницы. Каждая секция columnitemсодержит в себе имя столбца таблицы (fielddescr) и имя поля (fieldname), из которого берутся данные.

Эта секция используется на странице-таблице.

<adddeleteeditpagefields>

   <columnitem>

      <fielddescr>Name</fielddescr>

      <fieldname>name</fieldname>

   </columnitem>

   <columnitem>

      <fielddescr>Description</fielddescr>

      <fieldname>description</fieldname>

   </columnitem>

</adddeleteeditpagefields>

 

TAG fields

Содержит информацию о полях формы страницы Webинтерфейса. Каждый элемент этой секции может содержать:

fielddescr

заголовок поля

fieldname

наименование поля

description

комментарии и описание

default_value

значение поля по умолчанию; если поле пустое, то ему будет присвоено указанное значение;

необязательное поле;

required

требование обязательного заполнения поля; указывает что поле должно обязательно иметь значение;

Необязательное поле;

type  

типполя (checkbox; input, password; textarea; select; interfaces_selection)

encoding

вид кодировки текстового поля ‘textarea’ (например 'base64’);

необязательное поле;

 

Типы элементов управления:

interfaces_selection

специальный тип поля, содержит список интерфейсов pfSenseСубопция <multiple/>позволяет выбрать несколько элементов использую клавишу Ctrl.

checkbox

checkbox, может иметь 2 состояния: ‘выбрано' и 'не выбрано’ (on/off). Может содержать опцию 'enablefieldsсо (списком имен зависимых полей), которая указывает какие поля будут включаться/отключаться этим элементом.

input

поле для ввода однострочного текста. Может дополняться полем <size>, которое определяет ширину элемента

password

то-же, что и 'input, только отображает  введенный текст как звездочки; используется для ввода паролей

textarea

поле ввода многострочного текста. Может дополняться полями <cols> и <rows>, определяющими размеры элемента.

select

Поле выбора значения из списка. Содержит список пар значений имя-значение

<name>one</name><value>1</value>

 

<fields>

    <field>

       <fielddescr>Checkbox field</fielddescr>

       <fieldname>checkbox_val</fieldname>

       <description>

            This is checkbox field.

             Config value format: 'on'/'off'.

       </description>

       <type>checkbox</type>

    </field>

    <field>

       ...

    </field>

</fields>

 

TAG rowhelper

В дополнение к простым полям формы существует составной вид поля формы, состоящий из группы элементов управления. Это вид поля поддерживает многоэлементный набор данных, то есть вы можете добавлять/удалять наборы данных в список этого поля.

<field>

   <fielddescr>Rowhelper field example.</fielddescr>

   <type>rowhelper</type>

   <rowhelper>

      <rowhelperfield>

         <fielddescr>Sel</fielddescr>

         <fieldname>rsel</fieldname>

         <type>checkbox</type>

      </rowhelperfield>

      <rowhelperfield>

         <fielddescr>Name</fielddescr>

         <fieldname>name</fieldname>

         <type>input</type>

         <size>50</size>

      </rowhelperfield>

   </rowhelper>

</field>

 

События формы страницы

 

Следующие тэги содержат код, исполняемый при определенных событиях формы страницы. Секции могут содержать phpкод или вызов функций из INCфайла.

 

TAG custom_php_validation_command

Содержит команды, исполняемые при проверке данных полей формы страницы.

В примере ниже в аргументах содержатся глобальные переменные '$_POST’, в которой хранятся все передаваемые из формы  данные, и ‘&amp;$input_errors’, куда функция будет возвращать ошибки  проверки данных. В переменной  $_POSTнаходятся значения полей формы, доступные по имени (например $_POST['my_field_name']).

Обязательная для всех страниц секция.

<custom_php_validation_command>

        mypkg_validate($_POST, &amp;$input_errors);

</custom_php_validation_command>

 

TAG custom_php_resync_config_command

Содержит команды, исполняемые при синхронизации конфигурации приложения FreeBSD.

Вызывается при сохранении формы, загрузке pfSense, и при некоторых других системных событиях. Обычно это код, управляющий созданием нового конфигурационного файла и перезапуском пакета с новыми настройками.

Обязательная для всех страниц секция.

<custom_php_resync_config_command>

        mypkg_resync();

</custom_php_resync_config_command>

 

TAG custom_php_command_before_form

Содержит команды, исполняемые перед созданием формы.

Обычно используется для вставки кода JavaScriptперед формой.

<custom_php_command_before_form>

</custom_php_command_before_form>

 

TAG custom_php_after_form_command

Содержит команды, исполняемые после создания формы.

Обычно используется для вставки кода JavaScriptпосле формы.

<custom_php_after_form_command>

</custom_php_after_form_command>

 

TAG custom_php_after_head_command

Содержит команды, исполняемые после формирования заголовка Web страницы.

<custom_php_after_head_command>

</custom_php_after_head_command>

 

TAG custom_add_php_command_late

Содержит команды, исполняемые после добавления элементов в список.

<custom_add_php_command_late>

</custom_add_php_command_late>

 

TAG custom_delete_php_command

Содержит команды, исполняемые при удалении элементов из списка.

<custom_delete_php_command>

</custom_delete_php_command>

 

TAG custom_php_install_command

Содержит команды, исполняемые при инсталляции пакета.

Обычно здесь расположен код, который вносит в систему изменения, требуемые для работы приложения FreeBSD.

Эта секция присутствует только в основном XMLфайле.

<custom_php_install_command>

</custom_php_install_command>

 

TAG custom_php_deinstall_command

Содержит команды, исполняемые при удалении пакета.

Обычно здесь расположен код, который отменяет изменения, внесенные в систему при инсталляции пакета в секции custom_php_install_command, и убирает следы работы программы (каталоги, временные файлы, др.)

Эта секция присутствует только в основном XMLфайле

<custom_php_deinstall_command>

</custom_php_deinstall_command>

 

Пример пакета

Приведу пример простого пакета

Файл библиотеки PHP функций mypkg.inc :

<?php
/*
        mypkg.inc
*/
require_once('globals.inc');
require_once('config.inc');
require_once('util.inc');
require_once('pfsense-utils.inc');
require_once('pkg-utils.inc');
require_once('filter.inc');
require_once('service-utils.inc');
 
function mypkg_install()
{
}
 
function mypkg_deinstall()
{
}
 
function mypkg_validate_general($post, $input_errors)
{
    # check field 'input_val' for number value
    $inp = $post['input_val'];
    if (!empty($inp) && !is_port($inp))
        $input_errors[] = "Input field: You can insert only number!";
}
 
function mypkg_resync()
{
    global $config;
    $conf = $config['installedpackages']['mypkg']['config'][0];
}
?>
Пример конфигурационного XML файл пакета:
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE packagegui SYSTEM "../schema/packages.dtd">
<?xml-stylesheet type="text/xsl" href="/../xsl/package.xsl"?>
<packagegui>
   <copyright>
        <![CDATA[
/*
    mypkg.xml
    Copyright (C) 2007 ...
    All rights reserved.
*/
        ]]>
   </copyright>
   <!-- Package info section -->
   <description>This is a test package</description>
   <requirements>Describe your package requirements here</requirements>
   <faq>Currently there are no FAQ items provided.</faq>
   <name>mypkg_tbl</name>
   <version>1.0.0</version>
   <category>Test</category>
   <!-- Page link files -->
   <include_file>/usr/local/pkg/mypkg.inc</include_file>
   <!-- Page title -->
   <title>Services: My package -> Table</title>
   <!-- Page operation info. This info placed to the config modification -->
   <addedit_string>A mytest_tab package has been created/modified.</addedit_string>
   <delete_string>A mytest_tab package has been deleted.</delete_string>
   <!-- Page navigation tabs -->
   <tabs>
      <tab>
         <text>General</text>
         <url>/pkg_edit.php?xml=mypkg.xml&amp;id=0</url>
      </tab>
      <tab>
         <text>Table</text>
         <url>/pkg.php?xml=mypkg_tbl.xml</url>
         <!-- Current active tab -->
         <active/>
      </tab>
   </tabs>
   <!-- Page table columns -->
   <adddeleteeditpagefields>
      <!-- Use field names from 'fields' section -->
      <columnitem>
         <!-- Column name -->
         <fielddescr>Checkbox field</fielddescr>
         <!-- Column field value !not use 'name_fld' format, '_' symbol incolumn name have bag! -->
         <fieldname>checkboxval</fieldname>
      </columnitem>
      <columnitem>
         <fielddescr>Input field</fielddescr>
         <fieldname>inputval</fieldname>
      </columnitem>
      <columnitem>
         <fielddescr>Select field</fielddescr>
         <fieldname>selectval</fieldname>
      </columnitem>
   </adddeleteeditpagefields>
   <!-- Page fields -->
   <fields>
      <field>
         <fielddescr>Checkbox field</fielddescr>
         <fieldname>checkboxval</fieldname>
         <description>This is checkbox field. Config value format: 'on'/'off'.</description>
         <type>checkbox</type>
      </field>
      <field>
         <fielddescr>Input field</fielddescr>
         <fieldname>inputval</fieldname>
         <description>
         This is input field (size 100). Restriction: you can insert onlynumber.
         </description>
         <type>input</type>
         <size>100</size>
      </field>
      <field>
         <fielddescr>Select field</fielddescr>
         <fieldname>selectval</fieldname>
         <description>
         This is 'select' type field. If you selected option by 'name' -value will set by 'value'.
         </description>
         <type>select</type>
         <default_value>1</default_value>
         <options>
            <option><name>No  option</name><value>0</value></option>
            <option><name>One option</name><value>1</value></option>
            <option><name>Two option</name><value>2</value></option>
         </options>
      </field>
   </fields>
<!-- Page behavior options -->
<custom_php_validation_command>
   <!-- validate this page data -->
   mypkg_validate_general($_POST, &amp;$input_errors);
</custom_php_validation_command>
<custom_php_resync_config_command>
   <!-- update|sync config from this page -->
   mypkg_resync();
</custom_php_resync_config_command>
<custom_php_install_command>
   <!-- nott used here -->
</custom_php_install_command>
<custom_php_deinstall_command>
   <!-- nott used here -->
</custom_php_deinstall_command>
</packagegui>