Change the keep-alive timeout

Sets how many seconds the server waits for ping_req before closing the connection. The default is 300 seconds. Increase the timeout if the client cannot send ping_req often; decrease it if the server should free up the connections of vanished clients sooner.

Request and response: set_alive_timeout → alive_timeout_resp.
Access: a token of any access level.

Current ONS version

The server responds with alive_timeout_resp, not set_alive_timeout_resp as stated in the v0.17 description. The response has a status field but no operation_id. On error the server does not add error_text.

Request

Fields not marked as required may be omitted.

Field	Type	Description
cmd	string	set_alive_timeout
operation_id	string	May be passed, but the server does not return it in the response
timeout	uint16	Timeout in seconds, an integer from 1 to 65535. Without the field the server sets 300

{
    "cmd": "set_alive_timeout",
    "timeout": 600
}

Response

Field	Type	Description
cmd	string	alive_timeout_resp
status	uint8	1 — the timeout is changed, 2 — error
timeout	uint16	The new timeout, seconds. Only when status = 1
error_code	uint8	Only on error, see below

{
    "cmd": "alive_timeout_resp",
    "status": 1,
    "timeout": 600
}

Response to an invalid value:

{
    "cmd": "alive_timeout_resp",
    "status": 2,
    "error_code": 1
}

Errors

error_code	error_text	What happened
1	—	timeout is not an integer or is outside 1–65535, e.g. the string "600" or 600.5. The timeout has not changed

Good to know

• Only for the current connection. A new connection starts with 300 seconds again — set the timeout each time you connect.
• The countdown does not restart. The timeout is counted from the last ping_req or from the moment the connection was established, not from the moment of the change. If the new timeout is shorter than the time already elapsed, the connection is closed at the next check. Send ping_req right after the change.
• The check runs every 30 seconds. The connection is closed at the first check after the timeout expires, that is, with a delay of up to 30 seconds.

See also

• ping_req — reset the connection timer.
• Connection — how the server watches the connection.