OCCTL(8)

NAME
occtl - 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

AUTHORS
Written by Nikos Mavrogiannopoulos. Many people have contributed to it.

REPORTING BUGS
Issue tracker: https://gitlab.com/openconnect/ocserv/-/issues

COPYRIGHT
Copyright (C) 2013-2024 Nikos Mavrogiannopoulos and others, all rights reserved. This program is released under the terms of the GNU General Public License, version 2.

SEE ALSO
ocserv(8), ocpasswd(8)