Delegate-README.txt

В этой директории лежит delegate (универсальный прокси-сервер и сервер
контекта) для Windows. Остальные версии можно найти на сайте.

Вот примерный список функций:
* входящие (т.е. с вашего компьютера) соединение по протоколам
  HTTP, HTTPS, "HTTPS-tunnel", FTP, NNTP, Telnet, SOCKS и др.
* исходящие соеднинения (т.е. к настоящим серверам) по тем же
  протоколам, причём, например, можно FTP (на входе) пустить
  через SOCKS-прокси (или через HTTPS-прокси)
* кэширование запросов (с управляемыми параметрами)
* "прозначный" для протоколов прокси (с автоматическим исправлением
  адресов в HTTP и аналогичными функциями для других протоколов)
* аутентификация пользователей
* автоматически настраивает себя и запускается как сервис NT

Файлы в директории conf и delegatectl.cmd написаны мною самим. Их назначение -
упростить управление delegate под Windows.

Идея в том, что настройки delegate записываются в файл conf/foo.conf,
соответствующий порт (для передачи опции -P) в файл conf/foo.port, после
чего этой копией delegate можно управлять при помощи команд:

	delegatectl foo start              (запустить сервис)
	delegatectl foo stop               (остановить сервис)
	delegatectl foo restart            (перезапустить сервис)

Чтобы ещё упростить этот процесс, можно создать conf/foo.cmd с таким
содержимым:

	..\delegatectl %~n0 %*

и тогда этой копией delegate можно будет управлять, просто запуская
(из директории conf):

	foo start
	foo stop
	foo restart

В директории conf/ лежат файлы с настройками копий delegate, которые
использую я.


                        Краткое введение в Delegate
===============================================================================

Глава 1. Введение 
-----------------

Delegate - универсальный прокси-сервер с поддержкой множества протоколов и
функций. Научиться с ним работать не просто,

Одна запущенная копия Delegate:
- привязана к определенному порту или портам;
- ожидает запросы от клиентов с заданным(и) протоколом(-ами);
- либо обсулживает эти запросы сама, либо передаёт их другим серверам
  (первый случай называется режимом origin server, второй - proxy server);
- протокол, используемый клиентом (например, HTTP), можно не совпадать с
  протоколом (например, SOCKS), используемым для соединения с серверами.

Приблизительно, обработку запроса программой Delegate можно описать так:
1) принимается запрос (или начало запроса) от клиента;
2) выясняется, разрешены запросы от этого клиента с таким протоколом и прочими
   деталями;
3) выясняется, к какому серверу хочет подключиться клиент (или же к какому
   ресурсу, предоставляемому самим Delegate, он хочет обратиться);
4) выясняется, имеет ли право этот клиент обращаться к этому ресурсу;
5) находится сервер (например, выясняется его IP-адрес по URL);
6) собственно, клиент соединяется с сервером.

Всеми этапами этого процесса управляют параметры Delegate. К сожалению,
параметры эти задаются очень запутанными опциями командной строки.

При запуске под Windows NT программа Delegate создаёт сервис и спрашивает,
следует ли его запускать при каждой загрузке системы. Сервис однозначно
определяется тем, к какому порту привязан Delegate. 

К примеру, создать сервис и запустить Delegate можно командой:

        delegated.exe -P8080 SERVER=http ADMIN=your@email.com

Остановить и удалить сервис можно командой:

                   delegated.exe -P8080 -Fkill

Запущенный Delegate сообщает о включении таких протоколов, некоторые из которых
не знаю я сам: ftp-data,ftp,ftps,telnet,telnets,smtp,smtp-data,whois,domain,
dns,gopher,finger,http,httpft,https,ssltunnel,pop,pop3s,imap,imaps,ident,nntp,
nntps,news,nbt,prospero,archie,wais,tsp,ldap,ldaps,lpr,X,syslog,talk,socks,
socks4,socks5,icap,cuseeme,icp,http-proxy,pam,httpam,dgauth,delegate,tcprelay,
udprelay,udprelay1,teleport,coupler,vsap,sockmux,thruway,sftp.


Глава 2. Как сделать из Delegate нужный тип сервера
---------------------------------------------------

Первое, с чем вы столкнётесь - это как описать, чего же вы хотите от
Delegate. Для этого применяются опции SERVER и REMITTABLE.


2.1. SERVER
~~~~~~~~~~~

SERVER указывает, по какому протоколу Delegate общается с клиентами.
При SERVER=delegate разрешены почти все протоколы, и Delegate пытается
автоматически их определять. По умолчанию так и есть. Для SERVER можно 
указать и более специфичное значение, преследуя одну из двух целей.

Во-первых, опция вроде SERVER=http просто ограничит протоколы, на
которые могут претендовать клиенты. (Кроме того, можно указать дополнительные
ограничения, например, допускать запросы только на определенный адрес.)

Во-вторых, опция вроде SERVER=telnet создаёт сервер для протокола, для которого
невозможно автоматическое определение. Такой сервер способен обсуживать только
один протокол. (Конечно, на других портах сервер может обслуживать и другие
протоколы.)

В опции SERVER также можно указывать, куда разрешено подключаться с помощью
этого протокола. (Вернее, куда разрешено запрашивать подключение с помощьюъ
этого протокола.) Если такое место подключения указано, сервер называется
связанным (bound), иначе несвязанным (unbound). Полный синтаксис SERVER:

    SERVER=protocol[://host[:portNum]][:-:MountOptions]

Полный формат MountOptions можно найти в документации по опции MOUNT; с помощью
этой конструкции можно задавать дополнительные условия (например, заданный сетевой
интерфейс или обязательное использование SSL) или параметры только для этого
протокола (например, локальные настройки кэширования).

Некоторые виды сервером можно комбинировать вместе, тогда как другие, как
упомянутый telnet, ни с чем не совместимы. Пример, приводимый в документации,
создаёт сервер для NNTP, SMTP и POP3 (здесь и далее приведена одна команда,
просто она очень длинная и разбита на строки):

    -P119,110,25
    SERVER="nntp://nntp.somewhere.com:-:{*:119}"
    SERVER="smtp://smtp.somewhereelse.com:-:{*:25}"
    SERVER="pop://pop.elsewhere.com:-:{*:110}"

Насколько я понимаю, ограничения, указываемые в SERVER, влияют только на то,
какие запросы будут приниматься. Они не имеют ничего общего с тем, куда
на самом деле будет обращаться Delegate для выполнения этих запросов.


2.2. Опция -P
~~~~~~~~~~~~~

Как вы заметили, опция -P указывает, на каких портах Delegate ожидает запросов
от клиентов. Все порты изначально равны; чтобы для разных портов использовать
разные настройки, придётся для каждой опции явно указывать порты, к которым она
применяется (а синтаксис для этого сильно зависит от самой опции).

В опции -P можно перечислить несколько портов и даже диапазоны портов. Если на
компьютере несколько сетевых карт, перед каждым портом (или диапазоном) можно
указать имя хоста или IP-адрес сетевой карты, только с которой будут приниматься
запросы. Например, -P1000-1100,192.168.68.79:8080,192.168.0.1:8888.


2.3. REMITTABLE
~~~~~~~~~~~~~~~

REMITTABLE указывает, по каким протоколам клиенты могут попросить обратиться к
внешним серверам. Это перечисленные через запятую протоколы, для каждого из
которых можно ещё указать допустимые порты и методы.

Простой пример: REMITTABLE="http,https/{80,443},gopher,ftp,wais" при заданном
SERVER=http делает Delegate HTTP-прокси для множества протоколов. При этом
через метод CONNECT разрешается соединяться только с портами 80 и 443, при
этом при обнаружении не-HTTPS трафика соединение разорвётся. (Чтобы допустить
любые данные через метод CONNECT, нужно указать протокол ssltunnel вместо
протокола https.)

Методы указываются, например, так: REMITTABLE="http/80/GET". Специальный метод
readonly разрешает только методы, не изменяющие данных, например для Delegate,
работающего в режиме FTP-прокси, REMITTABLE="ftp//readonly" разрешает доступ к
FTP-серверам только на чтение.


Глава 3. Как заставить Delegate подключаться через другие прокси
----------------------------------------------------------------

Delegate может сам работать в качестве HTTP-прокси (SERVER=http) или в качестве
SOCKS-прокси (SERVER=socks). С другой стороны, он сам может исходящие
соединения делать через один из этих видов прокси (а также есть ещё несколько
экзотических вариантов).


3.1. Delegate, работающий через HTTP- или SOCKS-прокси
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Чтобы Delegate с SERVER=http использовал обычный HTTP-прокси в штатном режиме,
нужно всего лишь написать PROXY=сервер:порт. Аналогично, с помощью той же опции
Delegate с SERVER=ftp может использовать FTP-прокси, а при SERVER=telnet будет
использовать telnet-прокси. Обратите внимание, что опция PROXY задаёт именно
использование прокси-сервера, знающего о протоколе и особо его обрабатывающего.

Два других варианта используют внешний прокси в режиме, когда тот не знает, что
за данные через него проходят. Это возможно для SOCKS-прокси и некоторых видов
HTTPS-прокси. (Например, подходящий HTTPS-прокси может быть организован средствами
Delegate, есть задать REMITTABLE=ssltunnel.)

SOCKS-прокси используют опцией SOCKS=сервер:порт. HTTPS-прокси (обладающий
упомянутой способностью туннелирования) задают опцией SSLTUNNEL=сервер:порт.
Обе этих варианта можно использовать для туннелирования (направления через
прокси) любых протоколов, а не только HTTP, FTP и Telnet.

В случае опций PROXY и SOCKS можно задать, при подключении к каким серверам эти
опции действуют, перечислив их после двоеточия в формате HostList.
               
Формат HostList - это список серверов. Он применяется во многих командах и
довольно сложен, но зато обладает богатыми возможностями. Простой пример:

        SOCKS=foo.bar:1080:host1.somewhere.com,host2.somewhere.com

Можно использовать звёздочку ("*") для указания группы серверов, а также можно ставить
восклицательный знак, чтобы указать сервер(а), к которому(-ым) НЕ нужно
подключаться через прокси. Например, так:

        SOCKS=foo.bar:1080:!*.hnet.ru,!*.nsu.ru,!localhost

Можно также ограничивать порты, используя синтаксис сервер:{список_портов}.
Поищите в документации "HOSTLIST", чтобы узнать полный формат. (Можно даже
задавать ограничение по времени действия или по аутентифицированному
пользователю.)

Для примера запустим и воспользуемся каждым из видом прокси.

Создание SOCKS-прокси на fw.d.com:
    delegated -P1080 SERVER=socks

Создание обычного HTTP-прокси на fw.d.com:
    delegated -P8080 SERVER=http REMITTABLE=http,https,ftp

Создание туннелирующего HTTP-прокси на fw.d.com:
    delegated -P8888 SERVER=http REMITTABLE=http,ssltunnel,ftp

Использование внешнего SOCKS-прокси, дабы создать локальный HTTP-прокси
(ибо не все программы умеют ходить через SOCKS):
    delegated -P8080 SERVER=http REMITTABLE=* SOCKS=fw.d.com:1080

Использование внешнего HTTP-прокси, дабы создать локальный SOCKS-прокси
(т.к., аналогично, некоторые программы хотят SOCKS):
    delegated -P1080 SERVER=socks REMITTABLE=* SSLTUNNEL=fw.d.com:8888

Внимание: все приведённые виды прокси могут быть небезопасны, см. раздел про
управление доступом. Показанные команды не следует использовать в чистом виде.

Опции PROXY и SOCKS можно использовать несколько раз (в частности, с
разными параметрами).


3.2. Delegate, общающийся с другим Delegate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Можно запустить Delegate на двух компьютерах, чтобы один из них все запросы
пересылал через другого. Для этого удобнее всего на главном компьютере запустить
SERVER=delegate. Подчиненный компьютер (пересылающий запросы через главный)
тогда указывает главного опцией MASTER.

Запуск мастер-сервера на host1.mydomain.com:
    delegated -P9999 SERVER=delegate

Для использование мастер-сервера, чтобы созданить локальные SOCKS- и
HTTP-прокси, delegated нужно запустить с такими опциями:
    -P1080,8080
    SERVER="socks:-:{*:1080}"
    SERVER="http:-:{*:8080}"
    MASTER=host1.mydomain.com:9999

(Заметим, что неплохо было бы ограничить компьютеры, с которых можно использовать
мастер-сервер. См. раздел про управление доступом.)

Как и в SOCKS и PROXY, в MASTER можно после двоеточия написать список серверов,
при обращении к которым будет задействован этот прокси. Также опцию MASTER можно
использовать несколько раз.


3.3. ROUTE: обобщение MASTER и PROXY
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

ROUTE предписывает заданные (или все) запросы направлять через заданный сервер,
используя заданный протокол. Синтаксис таков:

    ROUTE=proto://host:port/-_-dstHostList:srcHostList

Опция ROUTE="delegate://сервер:порт/-_-dstHostList:*" эквивалентна опции
MASTER="сервер:порт:dstHostList".

Опция ROUTE="http://сервер:порт/-_-dstHostList:*" при SERVER=http эквивалентна
опции PROXY="сервер:порт:dstHostList".

Что ещё можно наворотить с помощью ROUTE, додумать предоставляется вам.


3.4. CONNECT: как управлять использованием прокси
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Как было сказано, в опциях PROXY, SOCKS, MASTER и ROUTE можно указывать условия,
когда они применимы. Это необходимо, если вы используете несколько опций одного
вида (несколько PROXY или несколько SOCKS), чтобы определить, какой прокси когда
задействовать.

Для управления тем, использовать ли прокси вообще (и тем, какой из видов прокси
использовать), удобнее использовать CONNECT.

CONNECT указывает, в каком порядке Delegate пытается удовлетворить запрос
пользователя. Варианты такие (перечислять через запятую):

  cache   -   из кэша (если этот вариант перечислен, он всегда используется
              первым; если не перечислен, кэш не используется)
  icp 	  -   через PROXY, используя ICP
  proxy   -   через PROXY
  master  -   через PROXY или MASTER
  https   -   через SSLTUNNEL
  vsap    -   через VSAP
  direct  -   прямое соеднинение
  socks   -   через SOCKS
  udp     -   прямое соединение через UDP (не TCP)
  None    -   не соединяться

Разумеется, CONNECT можно указать несколько, и у них могут быть условия. Формат
таков:

                     CONNECT=способы:протоколы:куда:откуда

Способы - это перечисление вроде cache,socks,direct. (Можно сокращать до первой
буквы: c,s,d.) Протоколы - перечисление протоколов, как в REMITTABLE. Куда и
откуда - перечисление серверов в формате HostList, как описано для SOCKS.

Реальный пример использования:

  CONNECT="cache,socks:*:!*.hnet.ru,!*.nsu.ru,!localhost" CONNECT="direct:*:*"

(Запросы к *.hnet.ru и *.nsu.ru обслуживаются локально и не кэшируются,
остальные направляются через прокси и кэшируются.)


3.5. Другие возможности
~~~~~~~~~~~~~~~~~~~~~~~

Delegate может принимать TCP-подключения, приходящие на другой компьютер,
смотри опцию VSAP.

Delegate может управлять общим кэшем, которым пользуются несколько Delegate'ов
на разных компьютерах. См. опцию ICP и протокол icp.

Delegate может централизованно хранить данные для аутентификации и выдавать их
подчиненным Delegate'ам. См. опцию AUTHORIZER.


Глава 4. Кэширование
--------------------

Кэширование - на удивление простая тема. Оно включается автоматически и работает
без особого вмешательства. Точнее, по умолчанию оно включается, если найдена
директория для кэша (см. опцию CACHEDIR), а такой директории по умолчанию нет.

Однако, если указать CACHE=do, то такая директория будет создана, если она
не существует, и кэширование сразу заработает. Другие возможные опции - 
CACHE=no (отключить) и CACHE=ro (только для чтения).

Кэшируются ресурсы HTTP, FTP, NNTP и Gopher.

Устареванием данных кэша управляет опция EXPIRE. CACHEFILE задаёт способ
формирования имён файлов для скэшированных ресурсов.

Устаревшие ресурсы сами с диска никогда не удаляются, а просто игнорируются.
Чтобы регулярно уничтожать устаревшие ресурсы, нужно использовать опцию CRON:

                      CRON="0 3 * * * -expire 3"

(формат minute hour day month dayOfWeek action, число после -expire задаёт,
на протяжении какого количество дней неиспользуемые элементы могут находиться
в кэше).

Чтобы (избирательно) отключить кэширование, можно применить cache=no в
опции MOUNT или SERVER: SERVER=http:-:cache=no. Однако универсальным способом
для управления кэшированием является CONNECT. Если cache указан (а по умолчанию
он там есть), то кэширование производится, иначе нет.


Глава 5. Управление доступом
----------------------------

5.1. Удаленное администрирование
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Delegate предоставляет Web-интерфейс для управления собой. Чтобы его задействвать,
выделите специальный порт в опции -P: -P1080,1081/admin (порт 1081 станет портом
для администрирования), добавьте опцию AUTH и заходите на

                      https://сервер:1081/-/admin/

Опция AUTH в нашем случае выглядит примерно так:
       
        AUTH=admin:-list{andreyvit:MD5:f561aaf6ef0bf14d4208bb46a4ccb3ad}

Здесь используется MD5-хэш пароля, но можно вместо MD5:хэш написать просто пароль
открытым текстом.

См. описание AUTH для дополнительной информации.


5.2. Компьютеры, с которых принимаются соединения
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

См. опцию RELIABLE в документации. Я её использую так:

    RELIABLE="localhost,-127.0.0.1,-192.168.0.1,-192.168.0.2,-192.168.68.79"

(минус перед IP-адресом указывает Delegate не обращаться в DNS для выяснения
соответствующего символического адреса).


(Остальная часть главы не дописана, как, вообще говоря, и вся глава.)


Глава 6. Заключение
-------------------

Теперь вы сможете найти все недостающие вам возможности в документации, благо,
она сосредоточена в одном файле. Рекомендую начать с прочтения разделов
DESCRIPTION и PARAMETERS.

Я сейчас использую следующие опции:

-P8080,8088/admin
SERVER=http
ADMIN=andreyvit@gmail.com
CONNECT="cache,socks:*:!*.hnet.ru,!*.nsu.ru,!localhost"
CONNECT="direct:*:*"
SOCKS=localhost:1080
REMITTABLE="http,ssltunnel,gopher,ftp,wais"
CACHE=do
RELIABLE="localhost,-127.0.0.1,-192.168.0.1,-192.168.0.2,-192.168.68.79"
CRON="0 3 * * * -expire 3"

Наконец, если этот файл к вам каким-то образом попал без самой программы, то
её без труда можно найти на http://www.delegate.org/.