==== Services =====
== Services ==
{{en:small_icons:services2_list.png|}} //// These are services managing the upgrade of the server's configuration. Each server has a set of configuration files //filegens// that will be  upgraded on a dedicated server if the relevant points are changed in the panel. Three states of the server are :\\
//Synced// - the data in the panel correspond to the server's configuration;\\
//Pending rebuild// - the changes have been made in the panel and the upgrade of the configuration is about to take place;\\
//Rebuild blocked// - an error occurred during upgrade, the automatic upgrade is blocked. The error will be shown in the graph  //Error// \\
The uprade of the configuration doesn't take place instantly! Once the changes in the panel have been made, the service should be in the status //Pending rebuild//. In about two minute's time the status will be changed to  //Synced//, which means the necessary changes have been made on the server.\\
You can also find the section //filegens// in the menu //actions//. //Filegens// are templates of all the files uploaded to the server.\\
== Filegens ==
//Filegens// is a simple way of generating any configs out of the database without any extra code.\\
Let's consider a small example of generating the config  //vhosts.conf// for the apache web server.\\
Move to //base/services//, add to the service webserver a new generator test. \\

//**Name**// - is the name //filegen//. During the  services rebuild the order of generator activation is determined by it.\\
//**Filename**// - the name of the file where the result of generation will be stored. If the type of the generator //script// and Filename aren't specified, the temporary file, is used which is deleted later.\\
//**Start mark**// - if the file has to be merged into the other, it marks the beginning of the generated section. This field should be left empty, if the file is to be changed.\\
//**End mark**// - similar to //Start mark//. It's not used, if the //Start mark// isn't specified.\\
//**File permissions**// - a numeric mode from four digits giving access to the file. If it's not specified, the permission to the existing file on a dedicated server is used.\\
//**Template**// - the template of the file. The detailed structure of it: .\\

Итак, пример построения //apache_vhosts.conf//:\\
<code>
<TMPL_LOOP accounts_loop>
# HERE we loop over accounts
# sites of account <TMPL_VAR login>
<TMPL_LOOP hosts_loop> # embedded loop of bound to account hosts
<VirtualHost *:80>
  ServerName <TMPL_VAR name>
  ServerAlias <TMPL_LOOP aliases_loop><TMPL_VAR alias> </TMPL_LOOP> # one more embedded loop

# здесь используется backreferences и переменные из настроек
  DocumentRoot <TMPL_VAR GLOBAL_clients_home>/<TMPL_VAR accounts_loop.login>/domains/<TMPL_VAR name>/html 

</VirtualHost>

</TMPL_LOOP> # closing hosts_loop
</TMPL_LOOP> # closing accounts_loop
</code>
Начинаем разбирать наш пример.\\
Первым делом желательно прочитать документацию по //HTML::Template//, //template-engine//, использующуюся при построении файлов. Достаточно понимать значение //TMPL_LOOP//, //TMPL_VAR//. Документация расположена по адресу [[http://html-template.sourceforge.net/]].\\
Каждый цикл индицируется названием //LOOPNAME_loop// и имеет ключ, к которому в темплейте можно обращаться как main_key. Например,\\
<code>
<TMPL_LOOP accounts_loop>
Account <TMPL_VAR login> have ID <TMPL_VAR main_key>
</TMPL_LOOP>
</code>
У каждого цикла есть параметры, в //accounts_loop// есть //login//, //passwd// и т.п.\\
Параметром может быть цикл, тогда он содержит поддерево данных, типа {//accounts_loop//}{//$account_id//}{//hosts_loop//}{$//host_id//}{//name//}.\\
В примере с //apache_vhosts.conf// это видно на //hosts_loop// и //aliases_loop//.\\
Особый пример представляет строка //DocumentRoot//, в которой используется сразу два приема, //backreference// и доступ к переменным из //настроек//.\\
//**backreference**// - это переменная, **НЕ ЛЕЖАЩАЯ** в текущей вложенности цикла. Как пример, мы приводим //accounts_loop.login//, который в //hosts_loop// не виден, так как хранится в //accounts_loop// (внешнем цикле).\\
//**GLOBAL**// - способ обратиться к переменным в //configure//. Убирается из имени //GLOBAL_// и вытаскивается переменная.\\

== Использование нескольких одинаковых циклов. ===
В случае, если нужно использовать в одном уровне вложенности несколько одинаковых циклов применяется следующий путь: \\
Пример (два цикла accounts_loop рядом): \\
<code>
Accounts: <TMPL_LOOP accounts_loop><TMPL_VAR login> </TMPL_LOOP>
Hosts: <TMPL_LOOP accounts_loop><TMPL_LOOP hosts_loop><TMPL_VAR name> </TMPL_LOOP></TMPL_LOOP>
</code>
работать **НЕ БУДЕТ**, так как в темплейте два одинаковых внешних цикла accounts_loop и система будет пытаться присвоить переменные от одного цикла другому, что будет вызывать ошибку. \\
Обходной путь - использовать номера в имени цикла. \\
Правильный пример: \\
<code>
Accounts: <TMPL_LOOP accounts_loop><TMPL_VAR login> </TMPL_LOOP>
Hosts: <TMPL_LOOP 2_accounts_loop><TMPL_LOOP hosts_loop><TMPL_VAR name> </TMPL_LOOP></TMPL_LOOP>
</code>
Обратите внимание, что во втором случае вместо accounts_loop стоит 2_accounts_loop - будет браться цикл accounts_loop, но не возникнет коллизии имен. \\

== Генерация нескольких файлов из одного темплейта. ==
Иногда необходимо сделать группу конфигурационных файлов. Как пример можно привести файлы зон //named// или виртуальных хостов //apache//. Самый простой способ деления - вставлять в темплейт метки начала деления //DK_NEW_FILE//. Пример: создаем файлы вирутальных хостов //apache//, по файлу на виртхост:\\
<code>
DK_NEW_FILE /usr/local/apache/conf.d/<TMPL_VAR name>.conf

  ServerName <TMPL_VAR name>
  ServerAlias <TMPL_LOOP aliases_loop><TMPL_VAR alias> </TMPL_LOOP> # one more embedded loop

DocumentRoot <TMPL_VAR domain_htdocs_dir> # domain_htdocs_dir изменяется при каждой итерации цикла hosts_loop

</code>
//DK_NEW_FILE// дает команду системе обработки темплейтов создать файл с именем, идущим после //DK_NEW_FILE// (/usr/local/apache/conf.d/<TMPL_VAR name> в данном случае) и с содержимым от текущей метки до следующей или конца темплейта.
метка //DK_NEW_FILE// должна находится в начале строки.\\