open-isns/files/man/ru/isnsadm.8

.TH ISNSADM 8 "11 мая 2007" "isnsadm 0.103" "Руководство системного администратора"
.SH ИМЯ
isnsadm - утилита клиента iSNS
.SH СИНТАКСИС
.B isnsadm
.RI [ опции... ]
.RI --register " объект...
.PP
.B isnsadm
.RB [ ... ]
.RI --query " атрибут" [= значение ]
.PP
.B isnsadm
.RB [ ... ]
.RI --deregister " атрибут=значение
.PP
.B isnsadm
.RB [ ... ]
.RI --list " тип атрибут=значение
.PP
.B isnsadm
.RB [ ... ]
.RI --dd-register " атрибут=значение
.PP
.B isnsadm
.RB [ ... ]
.RI --dd-deregister " dd-id атрибут=значение
.PP
.B isnsadm
.RB [ ... ]
.RI --enroll " имя-клиента атрибут=значение
.PP
.B isnsadm
.RB [ ... ]
.RI --edit-policy " атрибут=значение

.SH ОПИСАНИЕ
.B Isnsadm
- это утилита командной строки для взаимодействия с сервером iSNS.
Она работает в одном из нескольких взаимоисключающих режимов.
В настоящее время
.B isnsadm
поддерживает регистрацию, запросы и удаление регистрации.
.SH ОПЦИИ
По умолчанию,
.B isnsadm
берет большинство настроек из конфигурационного файла
.BR /usr/share/defaults/etc/isns/isnsadm.conf
или
.BR /etc/isns/isnsadm.conf ,
за исключением следующих опций:
.TP
.BI \--config " имя_файла\fR, " \-c " имя_файла
Эта опция переопределяет конфигурационный файл по умолчанию.
.TP
.BI \--debug " средство\fR, " \-d " средство
включает отладку. Допустимые средства:
.PP
.TS
tab(,),box,center;
lb|lr.
socket,отправка/получение данных по сети
auth,информация связанная с аутентификацией и безопасностью
message,уровень протокола iSNS
state,состояние базы данных
scn,сообщения SCN (уведомления об изменении состояния)
esi,сообщения ESI (запрос статуса сущности)
all,все вышеперечисленное
.TE
.PP
.TP
.BI \--local
заставляет
.B isnsadm
использовать локальный (Unix) сокет для связи с сервером iSNS.
Это может использоваться администратором для выполнения задач управления,
таких как регистрация новых клиентов, редактирование контроля доступа и т.д.
Локальный режим доступен только суперпользователю.
.TP
.BI \--server " имя_сервера\fR, " \-s " имя_сервера
указывает сервер для использования (если не указано в конфигурационном файле).
.TP
.BI \--control
заставляет
.B isnsadm
принимать идентичность управляющего узла. Управляющие узлы имеют больше прав
для доступа и изменения базы данных, чем обычные узлы хранения.
.PP
При использовании этой опции,
.B isnsadm
будет использовать имя источника и ключ DSA, указанные в параметрах конфигурации
.BR Control.SourceName " и " Control.AuthKeyFile соответственно.
.PP
.TP
.BI \--key " атрибут" = значение
Эта опция распознается только в режиме регистрации и позволяет указать ключ объекта.
Для более подробного объяснения см. раздел
.BR "Режим регистрации" .
.TP
.BI \--keyfile= имя_файла
При создании политики для нового клиента iSNS,
.B isnsadm
может сгенерировать ключ DSA для клиента. Публичная часть ключа сохраняется
в объекте политики в базе данных сервера iSNS, а приватная часть сохраняется
в файле, указанном в опции
.B keyfile .
.TP
.BI \--help
Выводит справочное сообщение и завершает работу.
.\"---------------------------
.SS Встроенная справка
.B Isnsadm
имеет встроенные функции справки. При вызове с
.BR \--help ,
выводится общее справочное сообщение, показывающее все поддерживаемые режимы команд,
и завершает работу. Специфическая справка по отдельному режиму команды доступна
при вызове этого режима с единственным аргументом
.BR help ,
например:
.PP
.B isnsadm --register help
.PP
Это выведет справочное сообщение, описывающее, как использовать этот режим команды,
а также список поддерживаемых атрибутов и поясняющий текст для каждого атрибута.
.\"---------------------------
.SS Поддерживаемые атрибуты
Большинство режимов команд принимают список атрибутов в качестве аргументов командной строки.
Названия и синтаксис этих атрибутов одинаковы для всех режимов команд,
однако некоторые режимы поддерживают только ограниченный набор атрибутов.
.PP
Атрибуты обычно задаются в виде пар
.IB имя = значение .
Там, где поддерживаются пустые (или NIL) атрибуты, можно указать только имя атрибута.
.PP
Синтаксис значения атрибута
.I значение
зависит от типа атрибута. Для строк и числовых значений особых соглашений нет,
но для битовых полей применяется специальный синтаксис, описанный ниже.
.PP
Имя атрибута обычно предваряется типом объекта, к которому он относится (например,
.BR entity ),
с последующим дефисом и самим именем. Однако там, где контекст явно определяет
конкретный тип объекта, префикс можно опустить. Например, при редактировании объекта
политики с помощью
.BR \--edit-policy ,
допустимо использовать
.B node-type
как сокращение для
.BR policy-node-type .
.PP
Аналогично, в команде запроса не допускается смешивание атрибутов разных типов объектов.
Таким образом, первый атрибут строки запроса устанавливает контекст типа, так что
следующие два вызова эквивалентны:
.PP
.B isnsadm --query pg-name=iqn.com.foo pg-addr=10.1.1.1 pg-port=860/tcp
.br
.B isnsadm --query pg-name=iqn.com.foo addr=10.1.1.1 port=860/tcp
.PP
.B Isnsadm
в настоящее время поддерживает следующие атрибуты:
.PP
.TS
tab(,),box,center;
li|lilili
lt|lbrlb.
Контекст,Атрибут,Тег iSNS,Псевдонимы
_
Сетевая сущность,entity-id,1,eid
\^,entity-prot,2
\^,entity-index,7
Узел хранения iSCSI,iscsi-name,32
\^,iscsi-node-type,33
\^,iscsi-alias,34
\^,iscsi-idx,36
\^,iscsi-authmethod,42
Портал,portal-addr,16
\^,portal-port,17
\^,portal-name,18
\^,portal-esi-port,20
\^,portal-esi-interval,21
\^,portal-idx,22
\^,portal-scn-port,23
Группа порталов,portal-group-index,52
\^,pg-name,48
\^,pg-addr,49
\^,pg-port,50
\^,pg-tag,51,pgt
\^,pg-idx,52
Домен обнаружения,dd-id,2065
\^,dd-name,2066
\^,dd-member-iscsi-idx,2067
\^,dd-member-name,2068
\^,dd-member-fc-name,2069
\^,dd-member-portal-idx,2070
\^,dd-member-addr,2071
\^,dd-member-port,2072
\^,dd-features,2078
Объект политики,policy-name,-,spi
\^,policy-key,-
\^,policy-entity,-
\^,policy-node-type,-
\^,policy-object-type,-
\^,policy-functions,-
.TE
.PP
.\"---------------------------
.SS Атрибуты портала
Информация о портале передается двумя отдельными атрибутами в iSNS:
атрибут адреса, содержащий IP-адрес, и атрибут порта TCP/UDP,
содержащий номер порта и указание используемого протокола (TCP или UDP).
.PP
При разборе порта TCP/UDP Open-iSNS ожидает номер порта,
за которым необязательно следует слэш и протокол. Имена портов,
такие как "iscsi-target", не поддерживаются.
.PP
Для удобства,
.B isnsadm
поддерживает нотацию, представляющую портал как один псевдоатрибут,
разделяя адрес и порт двоеточием. Таким образом, следующие два варианта эквивалентны,
причем второй является сокращенной формой первого:
.PP
.BI addr= <адрес> " port=" <порт> [/ протокол ] \fR.
.BI portal= <адрес> : порт [/ протокол ]
.PP
Эта нотация может использоваться в любом контексте, где может появляться пара атрибутов
.BR addr / port ,
и может предваряться именем типа, например,
.BR pg-portal=... .
.PP
При использовании литеральных IPv6-адресов адрес должен быть заключен в квадратные скобки,
иначе встроенные двоеточия создадут неоднозначность:
.BR portal=[2001:5c0:0:2::24]:860/tcp
.PP
.\"---------------------------
.SS Атрибуты битовых полей
Некоторые атрибуты iSNS представляют собой слова, представляющие битовое поле.
.B Isnsadm
отображает и разбирает эти атрибуты в удобочитаемой форме,
а не использует числовое значение. Названия значений битов отображаются
встроенными средствами справки. При указании атрибута битового поля
в командной строке их можно комбинировать с помощью символов плюс (\fB+\fP)
или запятой (\fB,\fR), например:
.PP
.B node-type=control+initiator
.PP
.\"---------------------------
.SS Режим регистрации
Режим регистрации выбирается с помощью опции
.B --register ,
за которой следует список одного или более объектов для регистрации на сервере iSNS.
По умолчанию это создаст сетевую сущность для клиента (если она еще не существует)
и поместит новые объекты внутрь нее. Обычно все объекты для сетевой сущности
регистрируются за одну операцию, а не по отдельности.
.PP
Каждый объект задается как тип, за которым необязательно следует список атрибутов,
разделенных запятыми, например:
.PP
.B target=iqn.2005-01.org.open-iscsi.foo:disk1,alias=disk1
.PP
В настоящее время поддерживаются следующие типы объектов:
.TP
.BI entity= имя
Указывает серверу группировать все объекты в указанном объекте-контейнере сетевой сущности.
Обычно сервер iSNS автоматически назначает имя сущности в соответствии со своими политиками,
и нет необходимости указывать его явно.
.TP
.BI initiator[= имя ]
Регистрирует узел хранения iSCSI типа initiator.
По умолчанию имя устанавливается равным имени источника iSNS.
.IP
За этим может следовать любое количество атрибутов узла хранения iSCSI.
.TP
.BI target[= имя ]
Регистрирует узел хранения iSCSI типа target.
По умолчанию имя устанавливается равным имени источника iSNS.
.IP
Этот объект принимает тот же набор атрибутов, что и
.BR initiator .
.TP
.BI control[= имя ]
Регистрирует узел хранения iSCSI типа control.
По умолчанию имя устанавливается равным имени источника iSNS.
Только управляющие узлы должны регистрироваться как узлы управления,
поскольку это дает узлу полный контроль над базой данных iSNS.
.IP
Этот объект принимает тот же набор атрибутов, что и
.BR initiator .
.TP
.BI portal=[ адрес:порт/протокол ]
Регистрирует портал с использованием указанной тройки адрес, порт и протокол.
Если тройка опущена,
.B isnsadm
использует IP-адрес хоста клиента. Если портал следует за регистрацией initiator
(в командной строке), порт по умолчанию равен 860/tcp; если за регистрацией target,
порт по умолчанию равен 3260/tcp.
Для мультикастовых хостов выбор адреса зависит от реализации.
.IP
За этим может следовать любое количество атрибутов портала.
.TP
.B pg
Регистрирует группу порталов, объединяющую предыдущий портал и узел.
Группы порталов могут использоваться для описания предпочтительных порталов
для данного узла; подробности см. в RFC 4171.
.IP
За этим может следовать любое количество атрибутов группы порталов.
Список атрибутов должен указывать тег группы порталов (PGT)
через атрибут
.BR pgt .
.PP
Есть две дополнительные опции командной строки, которые используются исключительно
в режиме регистрации. Одна из них —
.BR \--replace .
Обычно режим регистрации
.I добавляет
новые объекты к сетевой сущности, связанной с хостом клиента.
Если в командной строке указана опция
.B \--replace ,
сервер полностью очищает сетевую сущность и удаляет все порталы и узлы хранения,
которые она содержала. Затем создается новая сетевая сущность, в которую помещаются
порталы и узлы хранения, предоставленные вызывающей стороной.
.PP
Кроме того, можно заменить только части сетевой сущности. Это достигается
с помощью опции командной строки
.B \--key
для указания объекта, который должен быть заменен.
.PP
Например, предположим, что сетевая сущность содержит портал
.BR 10.1.1.1:860 ,
а сетевой адрес клиента изменился на
.BR 10.2.7.7 .
Тогда следующая команда атомарно обновит базу данных, заменив только портал,
не затрагивая зарегистрированные узлы хранения:
.PP
.B "  isnsadm --replace --key portal=10.1.1.1:860 portal=10.2.7.7:860
.PP
Опция
.B \--key
распознает только подмножество обычных атрибутов:
.RS
.TS
tab(,),box;
li|li
lb|lb.
Тип объекта,Синтаксис
_
Сущность,eid=\fIидентификатор
Портал,portal=\fIадрес\fP:\fPпорт
Узел iSCSI,iscsi-name=\fIимя
.TE
.RE
.PP
Чтобы получить список поддерживаемых атрибутов, вызовите
.BR "isnsadm --register help" .
.\"---------------------------
.SS Режим запроса
Режим запроса выбирается с помощью опции
.B --query .
Запрос состоит из списка пар
.BR атрибут = \fI значение .
Все атрибуты должны относиться к одному типу объекта,
т.е. запросы, смешивающие атрибуты сетевой сущности, например, с атрибутами портала,
будут отклонены.
.PP
Также возможно указать имя атрибута без значения (т.е. просто
.BR атрибут ),
что будет соответствовать любому объекту, имеющему такой атрибут, независимо от его значения.
Это полезно, когда вы хотите запросить все объекты данного типа.
.PP
Чтобы получить список поддерживаемых атрибутов, вызовите
.BR "isnsadm --query help" .
.\"---------------------------
.SS Режим списка
В этом режиме
.B isnsadm
отобразит все объекты заданного типа, при необходимости ограниченные теми,
которые соответствуют определенным значениям атрибутов.
.PP
Аргументы режима списка — это
.IR "имя типа" ,
за которым необязательно следует одна или несколько пар
.IB атрибут = значение .
Разрешены только атрибуты, относящиеся к указанному типу;
например, если вы указываете имя типа
.BR portals ,
разрешены только атрибуты порталов.
.PP
Возможные имена типов:
.BR entities ,
.BR nodes ,
.BR portals ,
.BR dds ,
.BR ddsets ,
.BR portal-groups ", и "
.BR policies .
.PP
Дополнительная информация доступна через
.BR "isnsadm --list help" .
.\"---------------------------
.SS Режим удаления регистрации
В этом режиме вы можете удалить ранее зарегистрированные объекты.
Только узел, который изначально зарегистрировал сущность, имеет право удалить ее
или любые ее дочерние объекты. (Управляющие узлы не ограничены этим правилом).
.PP
В режиме удаления регистрации список аргументов состоит из списка пар
.IB атрибут = значение .
Удаление регистрации поддерживает тот же набор атрибутов, что и режим запроса.
.\"---------------------------
.SS Регистрация домена обнаружения
Этот режим позволяет зарегистрировать домен обнаружения или добавить
новых членов в существующий домен обнаружения. Атрибуты указываются
в виде списка пар
.IB атрибут = значение .
Распознаются только атрибуты домена обнаружения.
.PP
Обратите внимание, что для добавления членов в существующий домен
необходимо указать числовой идентификатор домена. Символическое имя домена
не является допустимым дескриптором при обращении к домену обнаружения.
.\"---------------------------
.SS Режим удаления регистрации домена обнаружения
В этом режиме вы можете удалить ранее зарегистрированный домен обнаружения.
Только узел, который изначально зарегистрировал домен обнаружения,
имеет право удалить его или любых его членов. (Управляющие узлы не ограничены этим правилом).
.PP
В режиме удаления регистрации домена обнаружения список аргументов состоит
из идентификатора домена обнаружения, за которым следует список пар
.IB атрибут = значение .
Удаление регистрации домена обнаружения поддерживает тот же набор атрибутов,
что и режим запроса.
.\"---------------------------
.SS Регистрация клиента
Этот режим работает только тогда, когда сервер распознает клиента
как обладающего возможностями управляющего узла, что возможно двумя способами:
.TP
Вызов
.B isnsadm \--local
от имени суперпользователя на хосте, где работает
.B isnsd .
Опция
.B \--local
указывает использовать локальный управляющий сокет для связи с сервером.
.TP
Вызов
.BR "isnsadm \--control" ,
который указывает принять идентичность управляющего узла.
При использовании этой опции,
.B isnsadm
будет использовать имя источника и ключ DSA, указанные в параметрах конфигурации
.BR Control.SourceName " и " Control.AuthKeyFile соответственно.
Сервер должен быть настроен на предоставление этому идентификатору статуса управляющего узла.
.PP
Для регистрации клиента используйте опцию
.B \--enroll ,
за которой следует (исходное) имя клиента для регистрации.
Эта строка будет использоваться как имя политики безопасности,
которую клиент будет использовать для идентификации.
.PP
За этим следует список пар атрибут/значение, где поддерживается следующий набор атрибутов:
.PP
.TS
tab(,),box,center;
li|lilili
lb|lrlb.
Атрибут,Описание,Псевдонимы
_
name,Имя политики,spi
key,Публичный ключ DSA клиента
entity,Назначенный идентификатор сущности
node-type,Разрешенные тип(ы) узлов
node-name,Разрешенные имена узлов
functions,Битовое поле разрешенных функций
object-type,Маска доступа к объектам
.TE
.PP
Атрибут
.B key
используется для указания публичного ключа DSA, который сервер должен использовать
для аутентификации сообщений от этого клиента. Вы можете указать имя файла;
в этом случае
.B isnsadm
попытается прочитать публичный ключ в формате PEM из этого файла.
Если атрибут
.B key
не указан или используется
.BR key=gen ", " isnsadm
сгенерирует ключ DSA. Приватная часть вновь сгенерированного ключа будет сохранена
в файле, указанном в
.BI --keyfile= имя_файла \fR.
.PP
Атрибут
.B object-type
используется для указания типов объектов, к которым клиенту разрешен доступ.
Это список пар
.IB тип : разрешение ,
разделенных запятыми, где
.I тип
может быть любым из
.BR entity ", " iscsi-node ", " portal ", " portal-group ", " dd ", " ddset ", и " policy .
Разрешения могут быть либо
.BR rw ", либо " r .
.PP
Атрибут
.B functions
может использоваться для ограничения функций, которые клиенту разрешено вызывать.
Это битовое поле, использующее стандартные имена функций из RFC 4171, такие как
.BR DevAttrReg ", " DevAttrQry ", и т.д."
.PP
Для описания модели безопасности open-isns и политик
обратитесь к странице руководства
.BR isns_config (5) .
.PP
.BR "Важное замечание" :
Для генерации ключа DSA необходимо иметь установленные параметры DSA.
По умолчанию,
.B isnsadm
ожидает найти их в
.BR /etc/isns/dsa.params .
Эти параметры создаются вызовом
.B isnsd \--init
один раз на серверной машине. В качестве альтернативы можно использовать
следующую команду:
.PP
.ti +8
openssl dsaparam 1024 -out /etc/isns/dsa.params
.ti -8
.PP
где 1024 — выбранный размер ключа DSA в битах.
.SH ПРИМЕРЫ
Если вы хотите использовать Open-iSNS в режиме аутентификации,
сначала необходимо инициализировать ключ DSA сервера и параметры DSA.
Это можно сделать удобно с помощью
.PP
.B isnsd --init
.PP
Это создаст приватный и публичный ключи сервера и поместит их в
.B /etc/isns/auth_key
и
.BR auth_key.pub соответственно.
.PP
Следующая команда создаст объект политики для узла с именем
.B isns.control
и предоставит ему привилегии управления:
.PP
.B isnsadm --local --keyfile=control.key
.B --enroll isns.control \(rs
.br
.B "           node-type=ALL functions=ALL object-type=ALL
.PP
В процессе регистрации клиента это сгенерирует пару ключей DSA
и поместит приватную часть ключа в файл
.BR control.key .
Этот файл должен быть установлен как
.BR /etc/isns/control.key
на хосте, который вы хотите использовать как станцию управления iSNS.
.PP
Далее, необходимо создать объект узла хранения для станции управления:
.PP
.B isnsadm --local --register control
.PP
На станции управления вы можете затем зарегистрировать дополнительные хосты:
.PP
.B isnsadm --control --keyfile=somehost.key
.B --enroll iqn.2005-01.org.open-iscsi.somehost \(rs
.br
.B "           node-type=target+initiator
.PP
Снова, это сгенерирует пару ключей DSA и сохранит приватную часть ключа в auth_key.
Обратите внимание на использование опции
.B \--control ,
которая указывает
.B isnsadm
использовать идентичность управляющего узла вместо ключа и имени источника по умолчанию.
.PP
Затем необходимо скопировать
.B somehost.key
на хост клиента и установить его как
.BR /etc/isns/auth_key .
Аналогично, публичный ключ сервера (который находится в
.BR /etc/isns/auth_key.pub
на сервере) должен быть скопирован на машину клиента
и размещен в
.BR /etc/isns/server_key.pub .
.PP
По умолчанию, когда клиент регистрирует узел хранения (будь то initiator или target)
с iSNS, клиент не сможет видеть другие узлы хранения. Чтобы цели были видны
данному инициатору, необходимо создать так называемые домены обнаружения (или DD).
.PP
В настоящее время операции с членством в домене требуют привилегий администратора.
Будущие расширения могут позволить клиентам iSNS добавлять себя
в один или несколько DD при регистрации.
.PP
Чтобы создать домен обнаружения и добавить в него узлы, вы можете использовать
.PP
.B isnsadm --control --dd-register dd-name=mydomain \(rs
.br
.B "           member-name=iqn.org.bozo.client iqn.org.bozo.jbod ...
.PP
Чтобы добавить членов в существующий DD, необходимо указать числовой идентификатор домена —
использование имени DD, к сожалению, недостаточно (это требование RFC, а не проблема реализации):
.PP
.B isnsadm --control --dd-register dd-id=42 \(rs
.br
.B "           member-name=iqn.com.foo member-name=iqn.com.bar
.PP
Идентификатор DD можно получить, выполнив запрос по имени DD:
.PP
.B isnsadm --control --query dd-name=mydomain
.PP
В режиме управления вы также можете вручную регистрировать и удалять узлы и порталы,
если хотите исправить несоответствия в базе данных. Например, это зарегистрирует
узел и портал на хосте с именем client.bozo.org:
.PP
.B isnsadm --control --register entity=client.bozo.org \(rs
.br
.B "           initiator=iqn.org.bozo.client portal=191.168.7.1:860
.PP
Обратите внимание, что эта регистрация явно указывает сетевую сущность,
в которую помещаются новые объекты. Если это опустить,
новые объекты будут помещены в сущность с именем
.BR CONTROL ,
что определенно не то, что вы хотите.
.SH СМ. ТАКЖЕ
RFC 4171,
.BR isnsd (8),
.BR isns_config (5).
.SH АВТОРЫ
Олаф Кирх <olaf.kirch@oracle.com>