net.php¶

Network infrastructure management module: adding and removing IP addresses, blocking traffic, managing network port status, retrieving statistics, and displaying Cacti graphs.

API Methods¶

Method	Action	Description
`add_ipv4`	adding IPv4 addresses	Adds the specified number of IPv4 addresses to a server or assigns specific IP addresses. Supports automatic search for free IPs in a VLAN or manual specification of a list.
`block_ip`	blocking an IP address	Blocks the specified IP address on the server via BIRD or blackhole. Requires authentication.
`get_status`	getting port status	Returns the current status and configuration of the server's network port. Requires authentication.
`port_off`	disabling a network port	Disables the specified server network port and adds a block tag with the specified reason.
`port_on`	enabling a network port	Enables the specified server network port, removing the block (tag 'block') if it was not set by an administrator.
`remove_ipv4`	removing an IPv4 address	Removes the specified IPv4 address from the server. If the `remove_all` flag is passed, all addresses are removed.
`show_cacti`	getting a Cacti graph	Returns traffic monitoring graph data for the specified server and port from the Cacti system.
`show_ipv4_free`	getting a list of free IPv4 addresses	Returns a list of available IPv4 addresses for the specified server and interface in a given VLAN. Requires authentication.
`unblock_ip`	unblocking an IP	Removes the block from the specified IP address on the server. Requires access rights verification.

net/add_ipv4¶

Adds the specified number of IPv4 addresses to a server or assigns specific IP addresses. Supports automatic search for free IPs in a VLAN or manual specification of a list.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `add_ipv4`
id	✅	int	ID of the server to which IP addresses are added
amount	✅	int	Number of IP addresses to add (if specific IPs are not specified)
port	❌	string	Network interface name (e.g., eth0, ipmi). If not specified, the primary interface is used.
vlan	❌	int	VLAN ID for IP assignment. For clients, it is determined automatically based on the interface.
ips	❌	`array<string>`	List of specific IP addresses to assign. If specified, `amount` is ignored.
ip	❌	string	A single IP address to assign (alternative to the `ips` array)
tag	❌	string	Subnet tag for selecting an IP pool (e.g., bm, ipmi, ovirt). Default is 'bm'.
fresh_period	❌	int	Freshness period for free IP data (in seconds). Default is -1.
allow_tech_networks	❌	int	Flag to allow the use of technical networks (administrators only). 0 or 1.
token	✅	string	User authentication token

Example Request

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

Example of a successful response

{
"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"
]
}

Failure response

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

```

net/block_ip¶

Blocks the specified IP address on the server via BIRD or blackhole. Requires authentication.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `block_ip`
token	✅	string	User authentication token
id	❌	int	Server ID. If not specified by the client, the system will attempt to find the server by IP.
ip	✅	string	IP address to block
description	❌	string	Reason for blocking or comment
four_hours	❌	int	Flag for temporary blocking for 4 hours (1 - yes, 0 - no)

Example Request

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

Example of a successful response

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

Failure response

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

```

net/get_status¶

Returns the current status and configuration of the server's network port. Requires authentication.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_status`
token	✅	string	User authentication token
id	✅	int	Server identifier
port	❌	string	Port name (e.g., eth0, ipmi). If not specified, the primary interface is used.
vlan	❌	string	VLAN identifier
speed	❌	string	Port speed
port_security	❌	string	Port security settings
trunc	❌	string	Data truncation parameter
status	❌	string	Status filter
duplex	❌	string	Duplex mode
port_virt_node	❌	string	Port virtual node identifier

Example Request

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

Example of a successful response

{
"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
}
}

Failure response

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

```

net/port_off¶

Disables the specified server network port and adds a block tag with the specified reason.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `port_off`
token	✅	string	User authorization token
id	✅	int	Server identifier
port	❌	string	Port name (e.g., eth0). If not specified, the primary interface is used.
reason	❌	string	Reason for port blocking. If specified, it is added to the block tag.

Example Request

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

Example of a successful response

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

Failure response

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

```

net/port_on¶

Enables the specified server network port, removing the block (tag 'block') if it was not set by an administrator.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `port_on`
token	✅	string	User authorization token
id	✅	int	Server identifier
port	❌	string	Port name (e.g., eth0). If not specified, the primary interface is used.

Example Request

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

Example of a successful response

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

Failure response

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

net/remove_ipv4¶

Removes the specified IPv4 address from the server. If the remove_all flag is passed, all addresses are removed.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `remove_ipv4`
token	✅	string	User authorization token
id	✅	int	Server identifier
ip	✅	string	IPv4 address to remove
remove_all	❌	int	Flag to remove all IP addresses (0 or 1)

Example Request

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

Example of a successful response

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

Failure response

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

net/show_cacti¶

Returns traffic monitoring graph data for the specified server and port from the Cacti system.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `show_cacti`
token	✅	string	User authentication token
id	✅	int	Server identifier
port	❌	string	Port name (e.g., eth0, ipmi). If not specified, the primary interface is used.
graph	❌	int	Graph identifier in Cacti. Default is 1.

Example Request

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

Example of a successful response

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

Failure response

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

net/show_ipv4_free¶

Returns a list of available IPv4 addresses for the specified server and interface in a given VLAN. Requires authentication.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `show_ipv4_free`
token	✅	string	User authentication token
id	✅	int	Server ID for which free IPs are searched
port	❌	string	Interface name (e.g., eth0, ipmi). If not specified, the primary interface is used.
vlan	❌	int	VLAN ID. If not specified, it is determined automatically based on the interface.
ip	❌	string	Mask or specific IP for filtering the search
tag	❌	string	Network tag (e.g., bm, ipmi, ovirt). Default is 'bm' for physical servers.
fresh_period	❌	int	Freshness period for ARP/MAC data in seconds. 0 or -1 to reset to default.
show_all	❌	int	Flag to show all free IPs (1) or only suitable ones (0). For clients, always 0.

Example Request

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

Example of a successful response

{
"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
}

Failure response

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

```

net/unblock_ip¶

Removes the block from the specified IP address on the server. Requires access rights verification.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `unblock_ip`
token	✅	string	User authorization token
id	❌	int	Server ID. If not specified, the system will attempt to find the server by IP (for clients).
ip	✅	string	IP address to unblock

Example Request

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

Example of a successful response

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

Failure response

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