Occtl

occtl(8) – OpenConnect VPN server control tool

SYNOPSIS

occtl [OPTIONS…] [COMMAND]

DESCRIPTION

This a control tool that can be used to send commands to ocserv. When called without any arguments the tool can be used interactively, where each command is entered on a command prompt; alternatively the tool can be called with the command specified as parameter. In the latter case the tool’s exit code will reflect the successful execution of the command.

OPTIONS

-s, –socket-file=FILE: Specify the server’s occtl socket file. This option is only needed if you have multiple servers.
-j, –json: Output will be JSON formatted. This option can only be used with non-interactive output, e.g., ‘occtl –json show users’.
-n, –no-pager: No pager will be used over output data.
–debug: Provide more verbose information in some commands.
-h, –help: Display usage information and exit.
-v, –version: Output version of program and exit.

COMMANDS

Commands can be passed as arguments on the command line or entered interactively at the prompt when occtl is run without a command argument.

Informational commands

show status: Display server-wide statistics: uptime, number of active sessions, number of banned IPs, and other aggregate counters.
show users: List all currently connected users together with their session ID, assigned VPN IP address, and connection duration.
show user NAME: Display detailed information about a specific connected user, including their assigned addresses, group, and traffic statistics.
show id ID: Display detailed information about the connection identified by its numeric session ID.
show iroutes: List the internal routes that connected clients have advertised to the server via the iroute per-user/group configuration option. These routes are optionally redistributed to other clients when expose-iroutes is enabled.
show events: Display a live log of connection and disconnection events.

Session management

disconnect user NAME: Terminate the active VPN connection of the named user. The user’s session cookie remains valid; the user can reconnect immediately using the same cookie (subject to cookie-timeout).
disconnect id ID: Terminate the VPN connection identified by its numeric session ID. The session ID is shown by show users and show id. The cookie associated with that session remains valid.
terminate user NAME: Disconnect the named user and permanently invalidate all of their session cookies. The user must re-authenticate from scratch on the next connection attempt.
terminate id ID: Disconnect the connection identified by its numeric session ID and invalidate the associated cookie.
terminate session SID: Invalidate a session by its session ID (SID) without requiring an active connection. Use this to revoke a cookie held by a client that has already disconnected but whose session is still listed by show sessions valid.
show sessions all: List every known session, including sessions that are still in the authenticating state or have been disconnected but whose cookie has not yet expired.
show sessions valid: List only the sessions whose cookie is still valid for reconnection. A session appears here after authentication completes and disappears when the cookie expires or is invalidated by a terminate command.
show session SID: Display detailed information about the session identified by its session ID (SID) string, as shown in show sessions all or show sessions valid.

IP ban management

unban ip IP: Remove the specified IP address from the ban list immediately, regardless of the remaining ban-time. The address’s accumulated ban points are also cleared. See the max-ban-score, ban-time, and ban-reset-time directives in ocserv.conf(8).
show ip bans: List all IP addresses that are currently banned. An IP is banned when its accumulated score exceeds max-ban-score in ocserv.conf(8).
show ip ban points: List all IP addresses that have accumulated ban points, including those below the ban threshold. Useful for monitoring addresses that are approaching the ban limit.

Server control

reload: Signal the server to re-read its configuration file. Equivalent to sending SIGHUP to the main ocserv process. Options marked as non-reloadable in ocserv.conf(8) are not affected.
stop now: Gracefully shut down the server. Active VPN sessions are terminated before the process exits.

EXIT STATUS

0: Successful program execution.
1: The operation failed or the command syntax was not valid.

IMPLEMENTATION NOTES

This tool uses unix domain sockets to connect to ocserv.

EXAMPLES

The tool can be run interactively when run with no arguments. When arguments are given they are interpreted as commands. For example:

$ occtl show users

Any command line arguments to be used as options must precede the command (if any), as shown below.

$ occtl --json show users