net.php¶

Модуль управления сетевой инфраструктурой: добавление и удаление IP-адресов, блокировка трафика, управление состоянием сетевых портов, получение статистики и отображение графиков Cacti.

Методы API¶

Метод	Действие	Описание
`add_ipv4`	добавление IPv4 адресов	Добавляет указанное количество IPv4 адресов к серверу или назначает конкретные IP-адреса. Поддерживает автоматический поиск свободных IP в VLAN или ручное указание списка.
`block_ip`	блокировка IP-адреса	Блокирует указанный IP-адрес на сервере через BIRD или blackhole. Требует аутентификации.
`get_status`	получение статуса порта	Возвращает текущий статус и конфигурацию сетевого порта сервера. Требует аутентификации.
`port_off`	отключение сетевого порта	Отключает указанный сетевой порт сервера и добавляет тег блокировки с указанной причиной.
`port_on`	включение сетевого порта	Включает указанный сетевой порт сервера, снимая блокировку (tag 'block'), если она не установлена администратором.
`remove_ipv4`	удаление IPv4 адреса	Удаляет указанный IPv4 адрес с сервера. Если передан флаг remove_all, удаляет все адреса.
`show_cacti`	получение графика Cacti	Возвращает данные графика мониторинга трафика для указанного сервера и порта из системы Cacti.
`show_ipv4_free`	получение списка свободных IPv4 адресов	Возвращает список доступных IPv4 адресов для указанного сервера и интерфейса в заданной VLAN. Требует аутентификации.
`unblock_ip`	разблокировка IP	Снимает блокировку с указанного IP-адреса на сервере. Требует проверки прав доступа.

net/add_ipv4¶

Добавляет указанное количество IPv4 адресов к серверу или назначает конкретные IP-адреса. Поддерживает автоматический поиск свободных IP в VLAN или ручное указание списка.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `add_ipv4`
id	✅	int	ID сервера, к которому добавляются IP-адреса
amount	✅	int	Количество IP-адресов для добавления (если не указаны конкретные IP)
port	❌	string	Имя сетевого интерфейса (например, eth0, ipmi). Если не указан, используется основной интерфейс.
vlan	❌	int	ID VLAN для назначения IP. Для клиентов определяется автоматически по интерфейсу.
ips	❌	`array<string>`	Список конкретных IP-адресов для назначения. Если указан, amount игнорируется.
ip	❌	string	Один IP-адрес для назначения (альтернатива массиву ips)
tag	❌	string	Тег подсети для выбора пула IP (например, bm, ipmi, ovirt). По умолчанию 'bm'.
fresh_period	❌	int	Период свежести данных о свободных IP (в секундах). По умолчанию -1.
allow_tech_networks	❌	int	Флаг разрешения использования технических сетей (только для администраторов). 0 или 1.
token	✅	string	Токен аутентификации пользователя

Пример запроса

curl -s "https://invapi.hostkey.ru/net.php" -X POST \
--data "action=add_ipv4" \
--data "id=VALUE" \
--data "amount=VALUE" \
--data "token=HOSTKEY_TOKEN"

Пример успешного ответа

{
"result": "OK",
"action": "add_ipv4",
"id": 12345,
"ips": [
{
"ip": "192.168.1.100",
"mask": "255.255.255.0",
"gateway": "192.168.1.1",
"vlan": 100,
"status": "active",
"created_at": "2023-10-27T10:00:00Z"
}
],
"keys": [
"abc123def456"
]
}

Примеры ошибок

``` { "code": -1, "message": "net/add_ipv4: invalid request" }

```

net/block_ip¶

Блокирует указанный IP-адрес на сервере через BIRD или blackhole. Требует аутентификации.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `block_ip`
token	✅	string	Токен аутентификации пользователя
id	❌	int	ID сервера. Если не указан клиентом, система попытается найти сервер по IP.
ip	✅	string	IP-адрес для блокировки
description	❌	string	Причина блокировки или комментарий
four_hours	❌	int	Флаг временной блокировки на 4 часа (1 - да, 0 - нет)

Пример запроса

curl -s "https://invapi.hostkey.ru/net.php" -X POST \
--data "action=block_ip" \
--data "token=HOSTKEY_TOKEN" \
--data "ip=VALUE"

Пример успешного ответа

{
"result": "OK",
"action": "block_ip",
"callback": "7bc29eb23fb1b879b21fce509597f07c"
}

Примеры ошибок

``` { "code": -1, "message": "net/block_ip: Invalid IP" }

```

net/get_status¶

Возвращает текущий статус и конфигурацию сетевого порта сервера. Требует аутентификации.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `get_status`
token	✅	string	Токен аутентификации пользователя
id	✅	int	Идентификатор сервера
port	❌	string	Название порта (например, eth0, ipmi). Если не указан, используется основной интерфейс.
vlan	❌	string	Идентификатор VLAN
speed	❌	string	Скорость порта
port_security	❌	string	Настройки безопасности порта
trunc	❌	string	Параметр усечения данных
status	❌	string	Фильтр статуса
duplex	❌	string	Режим дуплекса
port_virt_node	❌	string	Идентификатор виртуального узла порта

Пример запроса

curl -s "https://invapi.hostkey.ru/net.php" -X POST \
--data "action=get_status" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE"

Пример успешного ответа

{
"result": "OK",
"action": "get_status",
"data": {
"id": 12345,
"port": "eth0",
"status": "up",
"speed": "1000",
"duplex": "full",
"vlan": 100,
"mac": "00:1A:2B:3C:4D:5E",
"ip": "192.168.1.10",
"traffic_in": 1024000,
"traffic_out": 512000
}
}

Примеры ошибок

``` { "code": -1, "message": "net/get_status: authentication required" }

```

net/port_off¶

Отключает указанный сетевой порт сервера и добавляет тег блокировки с указанной причиной.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `port_off`
token	✅	string	Токен авторизации пользователя
id	✅	int	Идентификатор сервера
port	❌	string	Имя порта (например, eth0). Если не указан, используется основной интерфейс.
reason	❌	string	Причина блокировки порта. Если указана, добавляется в тег блокировки.

Пример запроса

curl -s "https://invapi.hostkey.ru/net.php" -X POST \
--data "action=port_off" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE"

Пример успешного ответа

{
"result": "OK",
"action": "port_off",
"callback": "7bc29eb23fb1b879b21fce509597f07c"
}

Примеры ошибок

``` { "code": -1, "message": "net/port_off: authentication required" }

```

net/port_on¶

Включает указанный сетевой порт сервера, снимая блокировку (tag 'block'), если она не установлена администратором.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `port_on`
token	✅	string	Токен авторизации пользователя
id	✅	int	Идентификатор сервера
port	❌	string	Название порта (например, eth0). Если не указан, используется основной интерфейс.

Пример запроса

curl -s "https://invapi.hostkey.ru/net.php" -X POST \
--data "action=port_on" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE"

Пример успешного ответа

{
"result": "OK",
"action": "port_on",
"callback": "7bc29eb23fb1b879b21fce509597f07c"
}

Примеры ошибок

{
"code": -1,
"message": "net/port_on: admin ban could not be lifted this way, please contact support or abuse team."
}

net/remove_ipv4¶

Удаляет указанный IPv4 адрес с сервера. Если передан флаг remove_all, удаляет все адреса.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `remove_ipv4`
token	✅	string	Токен авторизации пользователя
id	✅	int	Идентификатор сервера
ip	✅	string	IPv4 адрес для удаления
remove_all	❌	int	Флаг удаления всех IP адресов (0 или 1)

Пример запроса

curl -s "https://invapi.hostkey.ru/net.php" -X POST \
--data "action=remove_ipv4" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE" \
--data "ip=VALUE"

Пример успешного ответа

{
"result": "OK",
"action": "remove_ipv4",
"id": 12345,
"ips": [
"192.168.1.100"
],
"keys": [
"abc123def456"
]
}

Примеры ошибок

{
"code": -1,
"message": "invalid IP 192.168.1.1 for server 12345 with token token_value"
}

net/show_cacti¶

Возвращает данные графика мониторинга трафика для указанного сервера и порта из системы Cacti.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `show_cacti`
token	✅	string	Токен аутентификации пользователя
id	✅	int	Идентификатор сервера
port	❌	string	Название порта (например, eth0, ipmi). Если не указан, используется основной интерфейс.
graph	❌	int	Идентификатор графика в Cacti. По умолчанию 1.

Пример запроса

curl -s "https://invapi.hostkey.ru/net.php" -X POST \
--data "action=show_cacti" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE"

Пример успешного ответа

{
"result": "OK",
"action": "show_cacti",
"callback": "https://cacti.example.com/graph_image.php?local_graph_id=12345"
}

Примеры ошибок

{
"code": -1,
"message": "net/show_cacti: invalid request"
}

net/show_ipv4_free¶

Возвращает список доступных IPv4 адресов для указанного сервера и интерфейса в заданной VLAN. Требует аутентификации.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `show_ipv4_free`
token	✅	string	Токен аутентификации пользователя
id	✅	int	ID сервера, для которого ищутся свободные IP
port	❌	string	Название интерфейса (например, eth0, ipmi). Если не указан, используется основной интерфейс.
vlan	❌	int	ID VLAN. Если не указан, определяется автоматически по интерфейсу.
ip	❌	string	Маска или конкретный IP для фильтрации поиска
tag	❌	string	Тег сети (например, bm, ipmi, ovirt). По умолчанию 'bm' для физических серверов.
fresh_period	❌	int	Период свежести данных ARP/MAC в секундах. 0 или -1 для сброса к дефолту.
show_all	❌	int	Флаг показа всех свободных IP (1) или только подходящих (0). Для клиентов всегда 0.

Пример запроса

curl -s "https://invapi.hostkey.ru/net.php" -X POST \
--data "action=show_ipv4_free" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE"

Пример успешного ответа

{
"result": "OK",
"action": "show_ipv4_free",
"id": 12345,
"ips": [
"192.168.1.10",
"192.168.1.11"
],
"subnets": [
"192.168.1.0/24"
],
"res": "success",
"total_ips": 2,
"fresh": -1
}

Примеры ошибок

``` { "code": -1, "message": "net/show_ipv4_free: invalid request - invalid id 0" }

```

net/unblock_ip¶

Снимает блокировку с указанного IP-адреса на сервере. Требует проверки прав доступа.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `unblock_ip`
token	✅	string	Токен авторизации пользователя
id	❌	int	ID сервера. Если не указан, система попытается найти сервер по IP (для клиентов).
ip	✅	string	IP-адрес, который необходимо разблокировать

Пример запроса

curl -s "https://invapi.hostkey.ru/net.php" -X POST \
--data "action=unblock_ip" \
--data "token=HOSTKEY_TOKEN" \
--data "ip=VALUE"

Пример успешного ответа

{
"result": "OK",
"action": "unblock_ip",
"callback": "7bc29eb23fb1b879b21fce509597f07c"
}

Примеры ошибок

{
"code": -1,
"message": "net/unblock_ip: Invalid IP"
}