net.php¶

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

Методы API¶

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

net/add_ipv4¶

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

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `add_ipv4`
token	✅	string	Токен авторизации
id	✅	integer	ID сервера
port	❌	string	Название сетевого интерфейса (например, eth0, ipmi)
ips[]	❌	array	Список IP адресов для добавления. Если пусто, выполняется подбор.
amount	❌	integer	Количество IP адресов для подбора (если ips не указан)
allow_tech_networks	❌	integer	Разрешить использование технических сетей (для администраторов)

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

curl -s "https://invapi.hostkey.ru/net.php" -X POST \
--data "action=add_ipv4" \
--data "token=HOSTKEY_TOKEN" \
--data "id=123" \
--data "port=eth0" \
--data "ips[]=192.168.1.10" \
--data "ips[]=192.168.1.11"

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

{
"result": "OK",
"action": "add_ipv4",
"id": 123,
"ips": [
{
"ip": "192.168.1.10",
"vlan": 100
}
],
"keys": [
"key_abc123"
]
}

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

``` { "code": -1, "message": "failed to add IPv4: error message from service" }

```

net/block_ip¶

Блокирует указанный IP-адрес для сервера через BIRD или blackhole. Если параметр description не передан, используется системный префикс владельца.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Действие (`block_ip` или `blackhole_ip`)
token	❌	string	Токен авторизации
id	❌	integer	ID сервера
ip	✅	string	IP-адрес для блокировки
description	❌	string	Причина блокировки (добавляется к префиксу)
four_hours	❌	integer	Установка временного ограничения (4 часа)

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

curl -s "https://invapi.hostkey.ru/net" -X POST \
--data "action=block_ip" \
--data "token=YOUR_TOKEN" \
--data "id=123" \
--data "ip=1.2.3.4" \
--data "description=Spam attack"

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

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

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

``` { "code": -1, "message": "failed to send BIRD management command" }

```

net/get_status¶

Возвращает текущее состояние и параметры сетевого интерфейса сервера (скорость, VLAN, статус, настройки безопасности)

HTTP-метод: POST

Параметры:

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

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

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": {
"port_id": 123,
"port": "eth0",
"vlan": 100,
"speed": "1000",
"status": "active",
"port_security": 1,
"trunc": "",
"duplex": "full",
"nic_id": 456
}
}

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

``` { "code": -1, "message": "invalid request for server id 0 with port eth0" }

```

net/port_off¶

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

HTTP-метод: POST

Параметры:

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

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

curl -s "https://invapi.hostkey.ru/net.php" -X POST \
--data "action=port_off" \
--data "id=12345" \
--data "port=eth0" \
--data "reason=Maintenance"

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

{
"result": "OK",
"action": "port_off"
}

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

``` { "code": -1, "message": "net: action required" }

```

net/port_on¶

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

HTTP-метод: POST

Параметры:

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

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

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

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

{
"result": "OK",
"action": "port_on",
"data": {
"id": 123,
"port": "eth0",
"status": "active"
}
}

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

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

```

net/remove_ipv4¶

Удаляет один или несколько IPv4 адресов с сервера. Если указан параметр remove_all, удаляются все IP-адреса (в зависимости от логики реализации backend). При успешном выполнении очищается PTR-запись в DNS.

HTTP-метод: POST

Параметры:

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

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

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

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

{
"result": "OK",
"action": "remove_ipv4",
"id": 123,
"ips": [
{
"ip": "192.168.1.1",
"vlan": 100
}
],
"keys": [
"key_abc123"
]
}

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

{
"code": -1,
"message": "No IP specificed",
"action": "remove_ipv4",
"id": 0,
"ips": []
}

net/show_cacti¶

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

HTTP-метод: POST|GET

Параметры:

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

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

curl -s "https://invapi.hostkey.ru/net.php" -X POST \
--data "action=show_cacti" \
--data "token=HOSTKEY_TOKEN" \
--data "id=123" \
--data "port=eth0" \
--data "graph=5"

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

{
"result": "OK",
"action": "show_cacti",
"data": {}
}

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

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

```

net/show_ipv4_free¶

Возвращает список доступных для назначения IPv4 адресов для конкретного сервера, порта и VLAN с учетом локации и тегов.

HTTP-метод: POST|GET

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `show_ipv4_free`
token	✅	string	Токен авторизации
id	✅	integer	ID сервера
port	❌	string	Название интерфейса (например, eth0, ipmi)
ip	❌	string	Базовый IP для поиска
tag	❌	string	Тег (может быть массивом или строкой)
show_all	❌	integer	Показывать все доступные адреса (0 или 1)
fresh_period	❌	integer	Период свежести данных

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

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

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

{
"result": "OK",
"action": "show_ipv4_free",
"id": 123,
"ips": [
{
"ip": "192.168.1.10",
"vlan": 100
}
],
"subnets": [
"192.168.1.0/24"
],
"res": {},
"total_ips": 2,
"fresh": -1
}

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

``` { "code": -1, "message": "can't find approppriate free IP (vlan: 100 tag: bm amount: -1 at US)" }

```

net/unblock_ip¶

Снимает блокировку с указанного IP-адреса через BIRD. Если действие выполняется клиентом, проверяется наличие соответствующей записи в описании интерфейса.

HTTP-метод: POST

Параметры:

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

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

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

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

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

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

``` { "code": -1, "message": "failed to send BIRD management command", "context": { "id": 123, "ip": "1.2.3.4" } }

```