Hpt_ro russian (koi8-r) readme: $Id: ro_readme_rus.txt,v 1.5 2003/01/10 23:44:36 i_zkh Rel $

     О ПРОГРАММЕ
     -----------

В большинстве случаев штатных средств HPT для ограничения доступа линков к эхам
вполне хватает. Но бывают ситуации, когда надо запретить писать "всем, кроме", 
или когда надо следить за сроком действия ограничения, и т.д. И тут тех
возможностей, которые предоставляются тоссером, либо недостаточно, либо их 
неудобно использовать. К счастью, разработчики HPT сделали очень удобную вещь - 
перловые хуки. Чтобы не прописывать ограничения непосредственно в тексте
скрипта filter.pl, был создан библиотечный модуль Hpt_ro.pm, который
позволяет вынести ограничения в отдельный конфиг и настраивать доступ,
не думая о перле и его синтаксисе.


    СОСТАВ
    ------

Hpt_ro.pm - библиотека функций. Является ядром пакета.

ro_parser.pl - по своему назначению напоминает tparser.exe: выводит результат
               обработки конфигов в удобном для изучения виде.

ro_purge.pl - удаляет из конфига правила с истёкшим сроком действия. Его можно
              время от времени запускать по крону или вручную.

ro.cfg - пример конфига.

ro_readme_rus.txt - эта дока.


    УСТАНОВКА
    ---------

Для работы пакета необходим HPT с включенной поддержкой перловых хуков и 
установленный Perl (версии не ниже 5.6.0). Если всё это есть, то можно 
переходить к установке пакета: 

1. Скопируйте файлы в какой-нибудь каталог. Это может быть (но не обязательно)
каталог HPT. Главное условие, чтобы ro_parser.pl, ro_purge.pl и Hpt_ro.pm
находились в одном каталоге.

2. Впишите в Hpt_ro.pm пути к конфигурационным файлам:

  my $defhptconf = "n:\\bin\\hpt\\config";
  $ro_conf = "n:\\bin\\hpt\\ro.cfg";

В первой строчке указывается полное имя конфига HPT, а во второй - имя 
собственного конфига пакета. Если определена переменная окружения FIDOCONFIG,
то имя конфига HPT берётся из неё.

Обратите внимание, что вместо одного обратного слеша надо ставить два.

3. Создайте новый или отредактируйте прилагаемый в качестве примера файл 
ro.cfg. Он не обязан называться именно ro.cfg или находиться там же, где 
скрипты пакета. Называйте как хотите и кладите куда хотите, только 
не забывайте прописать его полное имя в Hpt_ro.pm. 

4. После того, как файл ro.cfg (или как вы там его назвали) написан, для
проверки правильности конфигурации запустите ro_parser.pl. Объём выводимой
этим скриптом информации может быть весьма большим, поэтому лучше вывод
перенаправить в файл:

  perl ro_parser.pl > ro.txt

Если нужно посмотреть только линков с запретами, то наберите:

  perl ro_parser.pl denyonly > ro.txt

5. Если результат вас устроил, то самое время править filter.pl. Добавьте
в начало файла строчки

  use lib "n:\\bin\\hpt";
  use Hpt_ro;

где после 'use lib' в кавычках укажите путь, по которому находится Hpt_ro.pm.
Не забудьте, что вместо одного обратного слеша надо ставить два.

В функцию filter() впишите строчки:

  if ($area) {
    my $res = Hpt_ro::checkro($area,$pktfrom);
    return $res if $res;
  }


6. Запустите скрипт на компиляцию, чтобы проверить, что всё прописано верно:

  perl filter.pl

7. Установка закончена.


     В Н И М А Н И Е !
     -----------------

После любого изменения ro.cfg обязательно запускайте ro_parser.pl, чтобы 
убедиться, что конфиг не содержит ошибок. Если конфиг неправилен, то
filter.pl выполнится с ошибкой, HPT его отключит, и readonly перестанет 
действовать совсем.


     Формат ro.cfg
     -------------

Файл состоит из последовательности определения групп и правил. Группы можно
определять в любом месте конфига, но обязательно до первого использования
группы в правиле.

ГРУППА ЭХ описывается ключевым словом echogroup.

Описание группы может быть сделано в одну строчку:

 echogroup <groupname> echomask1 echomask2 ...

В этом случае эхи (маски эх) перечисляются после имени группы.

Если эх в группе много, то удобней многострочный формат:

 echogroup <groupname>
   echomask1 echomask2 echomask3 ...
   echomaski echomaski+1 ...
   ...
   echomaskn-1 echomaskn
 endechogroup

Одну и ту же группу можно определять многократно, при этом списки эх 
объединяются, например:

 echogroup sysops R50.SYSOP*
 echogroup sysops N5020.SYSOP*

полностью эквивалентно

 echogroup sysops R50.SYSOP* N5020.SYSOP*


ГРУППА ЛИНКОВ описывается аналогично:

 linkgroup <groupname> linkmask1 linkmask2 ...

или

 linkgroup <groupname>
   linkmask1 linkmask2 linkmask3 ...
   linkmaski linkmaski+1 ...
   ...
   linkmaskn-1 linkmaskn
 endlinkgroup

linkmask имеет формат d:d/d[.d], где d - это число или знак '*'. Линк
'd:d/d.0' эквивалентен 'd:d/d', т.е. нулевой пойнт ноды и адрес самой ноды - 
это одно и то же.

ПРИМЕЧАНИЯ:
- регистр имени группы имеет значение, т.е. sysops и SYSOPS - это разные 
группы.
- имена групп эх и линков могут совпадать, при этом они не перепутаются, так 
как хранятся в разных местах. Т.е. 'linkgroup all' и 'echogroup all' - это
разные непересекающиеся группы.
- имя группы эх не может начинаться с дефиса '-' (почему, написано ниже).

ПРАВИЛА имеют формат:

{deny|allow} {@linkgroup|linkmask} {@echogroup|echomask} [expiration date]

linkgroup - имя ранее описанной группы линков. Перед именем группы обязательно 
  надо добавлять символ '@';
linkmask - линк или маска линка;
echogroup - имя ранее описанной группы эх. Перед именем группы обязательно надо 
  добавлять символ '@'. Если имя группы начинается с символа '-', то это 
  означает ссылку на группу эх из конфига HPT (опция -g в echoarea). Например, 
  '@-A' - означает все эхи, которые согласно конфига HPT имеют группу 'A', т.е. 
  в их опциях указано '-g A';
echomask - имя или маска эхи;
expiration date - дата, после которой правило перестаёт действовать. Дата 
  задаётся в формате: dd.mm.yy. Может не указываться, тогда правило действует
  постоянно.

Правила, условно говоря, действуют следующим образом: каждая пара эха-линк,
переданная в функцию checkro(), по очереди сравнивается с правилами (если срок
действия правила истёк, то оно отбрасывается). При обнаружении совпадения, т.е.
когда и линк и эха совпадают с соответствующими масками в правиле, сравнение
прекращается, а совпавшее правило определяет, разрешено ли линку писать в эху.

ПРИМЕРЫ:

- Запретить писать в OSCOL.SYSOPS всем пойнтам, кроме 2:6037/1.28:

allow 2:6037/1.28 OSCOL.SYSOPS
deny 2:6037/1.* OSCOL.SYSOPS

- Запретить пойнтам писать в сисопские эхи:

echogroup sysopechoes R50.SYSOP* N5020.SYSOP*
deny 2:6037/1.* @sysopechoes

- От модератора получен "!", отключающий ноду от SUPER.ECHO до 31 декабря
2001 года включительно:

deny 2:6037/1.* SUPER.ECHO 31.12.01

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

# Маска *:*/*.* означает "все линки". Маска *:*/* не подходит, так как 
# означает "все ноды" и эквивалентна маске *:*/*.0
linkgroup all *:*/*.*

# Группа аплинков.
linkgroup uplinks 2:5020/52 2:5025/3 2:6037/9

# Эхи "только для чтения"
echogroup readonly
  HUMOR.FILTERED 
  1072.COMPNEWS            
  BOCHAROFF.MUST.DIE  BOCHAROFF.UNPLUGGED   
endechogroup

# разрешить писать аплинкам, ...
allow @uplinks @readonly
#  ...но запретить всем остальным
deny @all @readonly

Этот вариант теоретически позволяет одному аплинку писать в readonly эху, 
которую мы получаем у другого аплинка. Если такой поворот событий надо 
исключить, то придётся сделать некоторые телодвижения. Во-первых, в
конфиге HPT всем эхам, которые идут с разных аплинков присвоить разные группы. 
Пусть все эхи, которые идут с 2:5020/52 имеют группу A, эхи с 2:5025/3 - B, 
эхи с 2:6037/9 - С. Аплинкам надо также присвоить соответствующие linkgrp.
Тогда создаваемым аплинками эхам будут автоматически присваиваться нужные 
группы.
После того, как конфигурация HPT исправлена нужным нам образом, можно менять
ro.cfg:

linkgroup all *:*/*.*
echogroup readonly
  HUMOR.FILTERED 
  1072.COMPNEWS            
  BOCHAROFF.MUST.DIE  BOCHAROFF.UNPLUGGED   
endechogroup
# Разрешить аплинкам писать в получаемые от них эхи
allow 2:5020/52 @-A
allow 2:5025/3 @-B
allow 2:6037/9 @-C
# Всем остальным запретить писать в readonly-эхи.
deny @all @readonly

     КАК РАБОТАЕТ
     ------------

При первом обращении к функции checkro() считываются конфиг HPT и собственный
конфиг. Затем все линки всех эх, взятые из конфига HPT, прогоняются через
правила, и в результате формируются два двумерных хеша allow и deny (хеш - это
массив, в качестве индекса которого выступают не числа, а строки). Затем
переданные в функцию эха и линк проверяются на присутствие в одном из хешей.
Если присутствуют в allow, то линку можно писать в эху, если присутствуют в
deny, то запрещено. Такая предобработка даёт небольшую задержку при первом
обращении к функции, но в дальнейшем проверка происходит быстро.
Если в обоих хешах линк или эха отсутствуют, значит, или линк не подписан на
эху, или эха на ноде не существует, или линк подписался на эху и тут же написал
в неё письмо. В первых двух случаях проверку можно доверить HPT -
неподписанного линка он не пустит в эху, а несуществующую эху он либо создаст,
либо, если линку автосоздание запрещено, положит письмо в badmail. Только для
последнего, хоть и редкого, но возможного случая сделано повторное
перечитывание конфигов. Если после перечитывания линк и эха отсутствуют в хеше
deny, значит, либо линку разрешено писать в конференцию, либо это первые два
случая.


     ЛИЦЕНЗИЯ
     --------

Это совершенно свободно распространяемый софт. Можете его использовать как 
угодно и где угодно. :) Копирайт сохранять не обязательно. Автор, как это 
водится в подобных случаях, никакой ответственности за возможный ущерб, 
возникший в результате использования этого программного обеспечения, не несёт.


     Благодарности
     -------------

Большое спасибо: 
- создателям HPT - за удобный и надёжный тоссер
- авторам языка Perl - за универсальное средство для ленивых админов :)
- Фёдору Устинову - за идеи и FTrack
- всем хорошим фидошникам - за то, что вы есть.


     Редактор английской версии readme
     ---------------------------------

Igor Zakharoff (2:5030/290.36)


     Автора, автора!
     ---------------

Автор: Andrew Sagulin (Андрей Сагулин)
FIDO:  2:6037/1.28
e-mail: andrews42@users.sourceforge.net
ICQ: 128724384

