net.php¶

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

API Methods¶

Method	Action	Description
`add_ipv4`	add IPv4 addresses	Adds a specified number of IPv4 addresses to a server on a specific port and VLAN. Supports selecting specific addresses or automatic selection of free ones.
`block_ip`	block IP address	Blocks a specified IP address on the server via BIRD or blackhole. Accepts a block reason and a blackhole flag.
`get_status`	get network interface status	Returns the current status of the network interface (port) for the specified server. Automatically determines the port if not explicitly specified.
`port_off`	disable network port	Disables the specified network port of the server. If the `reason` parameter is passed, a block tag with the specified reason is added.
`port_on`	enable network port	Enables the specified network port of the server, removing the block (tag 'block') if it was applied by the user.
`remove_ipv4`	remove IPv4 addresses	Removes one or all IPv4 addresses from the specified server. Clears PTR records in DNS.
`show_cacti`	get Cacti graphs	Returns Cacti monitoring graph data for the specified server and port.
`show_ipv4_free`	get list of free IPv4 addresses	Returns a list of available free IPv4 addresses for the specified server, port, and VLAN. Supports filtering by tags and freshness period.
`unblock_ip`	unblock IP address	Unblocks a specified IP address on the server, removing block rules in BIRD and clearing block tags.

net/add_ipv4¶

Adds a specified number of IPv4 addresses to a server on a specific port and VLAN. Supports selecting specific addresses or automatic selection of free ones.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `add_ipv4`
token	✅	string	User authorization token
id	✅	int	Identifier of the server to which addresses are added
amount	✅	int	Number of IP addresses to add (if specific IPs are not specified)
port	✅	string	Name of the network interface (e.g., eth0, ipmi)
vlan	❌	int	VLAN ID for address assignment. If not specified, the interface VLAN is used or determined automatically
ip	❌	string	Specific IP address to add (if automatic selection is not used)
ips	❌	`array<string>`	Array of specific IP addresses to add. Accepts multiple values: ips[]=1.2.3.4&ips[]=1.2.3.5
tag	❌	string	Tag for the network (e.g., ipmi, ovirt, bm). Used to determine the subnet during automatic selection
allow_tech_networks	❌	int	Flag to allow adding addresses from technical networks (for administrators)
fresh_period	❌	int	Period in days for filtering 'fresh' IP addresses

Example Request

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

Example of a successful response

{
"result": "OK",
"action": "add_ipv4",
"id": 12345,
"ips": [
{
"IP": "192.168.1.10",
"vlan": 100
},
{
"IP": "192.168.1.11",
"vlan": 100
}
],
"keys": [
"job_key_abc123",
"job_key_def456"
]
}

Failure response

{
"code": -1,
"message": "Error adding IPv4 addresses"
}

net/block_ip¶

Blocks a specified IP address on the server via BIRD or blackhole. Accepts a block reason and a blackhole flag.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `block_ip`
token	✅	string	User authorization token
id	✅	int	ID of the server where the IP is located
ip	✅	string	IP address to block
description	❌	string	Reason for blocking (will be added to the description)
four_hours	❌	int	Flag for temporary blocking (4 hours)

Example Request

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

Example of a successful response

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

Failure response

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

net/get_status¶

Returns the current status of the network interface (port) for the specified server. Automatically determines the port if not explicitly specified.

HTTP Method: POST

Parameters:

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

Example Request

curl -s "https://api.hostkey.com/net.php" -X POST \
--data "action=get_status" \
--data "token=HOSTKEY_TOKEN" \
--data "id=12345" \
--data "port=eth0"

Example of a successful response

{
"result": "OK",
"action": "get_status",
"data": {
"id": 12345,
"port": "eth0",
"status": "up",
"speed": "10000",
"duplex": "full",
"vlan": 100,
"mac": "00:1A:2B:3C:4D:5E",
"ip": "192.168.1.10",
"switch_id": 50,
"switch_port": "Gi1/0/1",
"location": "AMS",
"port_security": 1,
"trunc": "none"
}
}

Failure response

{
"code": -1,
"message": "net/get_status: invalid request for server 12345 with port eth0"
}

net/port_off¶

Disables the specified network port of the server. If the reason parameter is passed, a block tag with the specified reason is added.

HTTP Method: POST

Parameters:

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

Example Request

curl -s "https://api.hostkey.com/net.php" -X POST \
--data "action=port_off" \
--data "token=HOSTKEY_TOKEN" \
--data "id=12345" \
--data "port=eth0" \
--data "reason=Abuse detected"

Example of a successful response

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

Failure response

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

net/port_on¶

Enables the specified network port of the server, removing the block (tag 'block') if it was applied by the user.

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, ipmi). If not specified, the primary port is selected automatically

Example Request

curl -s "https://api.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": "admin ban could not be lifted this way, please contact support or abuse team."
}

net/remove_ipv4¶

Removes one or all IPv4 addresses from the specified server. Clears PTR records in DNS.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `remove_ipv4`
token	✅	string	Authorization token to perform the action
id	✅	int	Identifier of the server from which IPs are removed
ip	✅	string	IPv4 address to remove. If not specified, the action is not performed
remove_all	❌	int	Flag to remove all IP addresses from the server (1 - remove all, 0 - only the specified one)

Example Request

curl -s "https://api.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": [
{
"ip": "192.168.1.10",
"vlan": 100,
"status": "removed"
}
],
"keys": [
"key_abc123",
"key_def456"
]
}

Failure response

{
"code": -1,
"message": "No IP specified"
}

net/show_cacti¶

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

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `show_cacti`
token	✅	string	User authorization token
id	✅	int	Server identifier
port	❌	string	Port name (e.g., eth0, ipmi)
graph	❌	string	Flag to display the graph (default 1)

Example Request

curl -s "https://api.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",
"data": {
"id": 12345,
"port": "eth0",
"graphs": [
{
"title": "Traffic In/Out",
"url": "https://cacti.example.com/graph.php?id=5678",
"image": "data:image/png;base64,iVBORw0KGgoAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
}
]
}
}

Failure response

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

net/show_ipv4_free¶

Returns a list of available free IPv4 addresses for the specified server, port, and VLAN. Supports filtering by tags and freshness period.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `show_ipv4_free`
token	✅	string	User authorization token
id	✅	int	Server identifier
port	✅	string	Name of the network interface (e.g., eth0, ipmi)
vlan	❌	int	VLAN ID. If not specified, it is determined automatically from the server interface
tag	❌	string	Tag for subnet filtering (e.g., bm, ipmi, ovirt)
ip	❌	string	Partial IP match for search (e.g., 192.168.1.)
fresh_period	❌	int	IP freshness period in seconds (0 or -1 to disable filter)
show_all	❌	int	Show all available IPs (available only for administrators)

Example Request

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

Example of a successful response

{
"result": "OK",
"action": "show_ipv4_free",
"id": 12345,
"ips": [
{
"ip": "192.168.1.10",
"vlan": 100,
"subnet": "192.168.1.0/24",
"location": "AMS",
"status": "free"
},
{
"ip": "192.168.1.11",
"vlan": 100,
"subnet": "192.168.1.0/24",
"location": "AMS",
"status": "free"
}
],
"subnets": [
{
"network": "192.168.1.0",
"mask": 24,
"broadcast": "192.168.1.255",
"total": 254,
"free": 2
}
],
"res": {
"total_found": 2,
"filtered": 0
},
"total_ips": 2,
"fresh": -1
}

Failure response

{
"code": -1,
"message": "invalid request - invalid id 0"
}

net/unblock_ip¶

Unblocks a specified IP address on the server, removing block rules in BIRD and clearing block tags.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `unblock_ip`
token	✅	string	User authorization token
id	✅	int	Identifier of the server where the IP is located
ip	✅	string	IP address to unblock

Example Request

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

Example of a successful response

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

Failure response

{
"code": -1,
"message": "permission denied to remove block for 192.168.1.1. Please contact support."
}