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 IPs or automatic selection of free ones.
`block_ip`	block IP	Blocks a specified IP address on the server via BIRD or blackhole. Requires a reason for the block.
`get_status`	get port status	Returns the current status of the server's network interface (up/down, speed, duplex, MAC).
`port_off`	disable port	Disables the server's network interface. Can add a block tag with a reason.
`port_on`	enable port	Enables the server's network interface. Removes the block tag if it was not set by an administrator.
`remove_ipv4`	remove IPv4 addresses	Removes a specified IPv4 address or all addresses from the server. Clears PTR records in DNS.
`show_cacti`	get Cacti graphs	Returns data or a link to a traffic graph for the specified server port from the Cacti monitoring system.
`show_ipv4_free`	find free IPv4	Returns a list of available free IPv4 addresses for the specified server, port, and VLAN.
`unblock_ip`	unblock IP	Unblocks a previously blocked IP address on the server. Requires administrator privileges or matching the block reason.

net/add_ipv4¶

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

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `add_ipv4`
token	✅	string	Authorization token
id	✅	int	Server ID
amount	✅	int	Number of IP addresses to add
port	✅	string	Network interface name (e.g., eth0)
vlan	❌	int	VLAN ID (optional, determined automatically for clients)
ip	❌	string	Specific IP address to add (if not specified, a free one is selected)
ips	❌	`array`	Array of specific IP addresses to add
tag	❌	string	Network tag (e.g., ipmi, ovirt, bm)
fresh_period	❌	int	IP freshness period (time in seconds)
allow_tech_networks	❌	int	Allow use of technical networks (for administrators)

Example Request

curl -s "https://api.hostkey.com/net.php" -X POST \
--data "action=add_ipv4" \
--data "token=HOSTKEY_TOKEN" \
--data "id=12345" \
--data "amount=2" \
--data "port=eth0" \
--data "vlan=100" \
--data "ips[]=192.168.1.10" \
--data "ips[]=192.168.1.11"

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": [
  "key_abc123",
  "key_def456"
]
}

Failure response

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

net/block_ip¶

Blocks a specified IP address on the server via BIRD or blackhole. Requires a reason for the block.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `block_ip`
token	✅	string	Authorization token
id	✅	int	Server ID
ip	✅	string	IP address to block
description	✅	string	Reason for blocking (description)
four_hours	❌	int	Set a temporary block for 4 hours (1 to enable)

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" \
--data "description=VALUE"

Example of a successful response

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

Failure response

{
"code": -1,
"message": "no IP 192.168.1.50 found on server 12345"
}

net/get_status¶

Returns the current status of the server's network interface (up/down, speed, duplex, MAC).

HTTP Method: GET|POST

Parameters:

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

Example Request

curl -s "https://api.hostkey.com/net.php" -X GET \
--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": {
  "port": "eth0",
  "status": "up",
  "speed": "10000",
  "duplex": "full",
  "mac": "00:11:22:33:44:55"
}
}

Failure response

{
"code": -1,
"message": "net/get_status: invalid request for server 12345 with port eth0",
"description": "Parameter validation error or lack of access rights"
}

net/port_off¶

Disables the server's network interface. Can add a block tag with a reason.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `port_off`
token	✅	string	Authorization token
id	✅	int	Server ID
port	❌	string	Interface name (e.g., eth0). If not specified, the primary interface is selected.
reason	❌	string	Reason for disabling (added to the block tag)

Example Request

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

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 server's network interface. Removes the block tag if it was not set by an administrator.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `port_on`
token	✅	string	Authorization token
id	✅	int	Server ID
port	❌	string	Interface name (e.g., eth0). If not specified, the primary interface or the first eth interface is used.

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 a specified IPv4 address or all addresses from the server. Clears PTR records in DNS.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `remove_ipv4`
token	✅	string	Authorization token
id	✅	int	Server ID
ip	✅	string	IP address to remove
remove_all	❌	int	Remove all IP addresses from the server (1 - yes, 0 - no)

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": [
  "192.168.1.10"
],
"keys": [
  "key_xyz789"
]
}

Failure response

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

net/show_cacti¶

Returns data or a link to a traffic graph for the specified server port from the Cacti monitoring system.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `show_cacti`
token	✅	string	Authorization token
id	✅	int	Server ID
port	❌	string	Interface name (e.g., eth0)
graph	❌	string	Graph type (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" \
--data "port=eth0" \
--data "graph=1"

Example of a successful response

{
"result": "OK",
"action": "show_cacti",
"data": {
  "graph_url": "https://cacti.example.com/graph.php?id=12345",
  "port": "eth0",
  "server_id": 12345
}
}

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.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `show_ipv4_free`
token	✅	string	Authorization token
id	✅	int	Server ID
port	✅	string	Interface name (e.g., eth0)
vlan	❌	int	VLAN ID (optional, used for administrators)
tag	❌	string	Network tag (e.g., bm, ipmi, ovirt)
fresh_period	❌	int	IP freshness period (in seconds, -1 if not set)
allow_tech_networks	❌	int	Allow technical networks (0 or 1)

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.20",
    "vlan": 100
  },
  {
    "IP": "192.168.1.21",
    "vlan": 100
  }
],
"subnets": [
  "192.168.1.0/24"
],
"res": "success",
"total_ips": 2,
"fresh": -1
}

Failure response

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

net/unblock_ip¶

Unblocks a previously blocked IP address on the server. Requires administrator privileges or matching the block reason.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `unblock_ip`
token	✅	string	Authorization token
id	✅	int	Server ID
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.50. Please contract support."
}