OCCTL(8)

📦
version 1.5.0 · 10 versions
, in epel 10, fedora 44

✨ NAME ✨

occtl — the OpenConnect VPN server control tool, straight out of section 8 of the System Manager's Manual. 💖 She's the little remote control for your VPN server and she serves.

🌸 SYNOPSIS 🌸

occtl [OPTIONS...] [COMMAND]

🦋 DESCRIPTION 🦋

Okay so bestie, listen. This is a control tool, and its whole job is sending commands to ocserv. That's it. That's the vibe. 🫶

When you call her with zero arguments, she goes full interactive mode — you get a command prompt and you just type each command in, one at a time, like texting your bestie. So cozy. ✨

OR, and hear me out, you can call her with the command already specified as a parameter. One and done, no small talk. And in that case, the tool's exit code will reflect whether the command actually executed successfully. Main character energy with receipts. 💅

💜 OPTIONS 💜

  • -s, --socket-file=FILE — tell her where the server's occtl socket file lives. You literally only need this if you're running multiple servers, so don't stress unless that's your life. 🎀
  • -j, --json — output comes out JSON formatted. But bestie, this one only works with non-interactive output, e.g. occtl --json show users. No interactive JSON for you, sorry not sorry. 💀
  • -n, --no-pager — no pager will be used over the output data. Raw and unfiltered, periodt.
  • --debug — gives you more verbose information in some commands. Basically the "tell me everything" button. 👑
  • -h, --help — display usage information and exit. The classic.
  • -v, --version — output version of program and exit. Vibe check on which build you're running. ⭐

🔥 COMMANDS 🔥

You can pass commands as arguments on the command line, OR you can type them interactively at the prompt when occtl is run without a command argument. Two paths, same destination, both iconic. 🌈

🍓 Informational commands

  • show status — display server-wide statistics: uptime, number of active sessions, number of banned IPs, and other aggregate counters. The whole dashboard, no cap. 📊
  • show users — list all currently connected users together with their session ID, assigned VPN IP address, and connection duration. Everyone's here, everyone's accounted for. 🫶
  • show user NAME — display detailed information about one specific connected user, including their assigned addresses, group, and traffic statistics. It's giving ✨personalized✨.
  • show id ID — display detailed information about the connection identified by its numeric session ID. Numbers only, bestie. 🔢
  • 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. Very niche, very powerful. 🧚
  • show events — display a live log of connection and disconnection events. It's the group chat where every join and leave gets announced. 💜

🎀 Session management

  • disconnect user NAME — terminate the active VPN connection of the named user. Important: the user's session cookie remains valid, so they can reconnect immediately using the same cookie (subject to cookie-timeout). It's a "brb" not a "goodbye". 😭
  • 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. Same deal, different lookup key.
  • terminate user NAME — disconnect the named user AND permanently invalidate all of their session cookies. They must re-authenticate from scratch on the next connection attempt. This one's serious, bestie. 🔥
  • terminate id ID — disconnect the connection identified by its numeric session ID and invalidate the associated cookie. Both things. At once. Slay.
  • 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. So useful, obsessed. 👑
  • 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. The full archive, no filtering.
  • 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. The "still active" list. ✨
  • 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. Single session, full tea. 🍓

🧚 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). Free them, bestie. 🕊️
  • 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). The naughty list. 💀
  • 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. It's giving "we see you and we're watching". 👀

💅 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. Fresh config, same process, gorgeous.
  • stop now — gracefully shut down the server. Active VPN sessions are terminated before the process exits. The polite goodbye, not the rage quit. 🌸

🌈 EXIT STATUS 🌈

  • 0 — successful program execution. We ate. 💅
  • 1 — the operation failed or the command syntax was not valid. It happens, bestie. 😭

⭐ IMPLEMENTATION NOTES ⭐

This tool uses unix domain sockets to connect to ocserv. That's the whole magic trick. 🎩

🫶 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. Order matters, bestie, do not test her.

$ occtl --json show users

💖 AUTHORS 💖

Written by Nikos Mavrogiannopoulos. Many people have contributed to it. We love a collaborative queen. 👑

🙈 REPORTING BUGS 🙈

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

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)

And that's the whole page, bestie — this one's dated June 2026, it's the occtl(8) page from the System Manager's Manual, and it lives in the source tree with the rest of the ocserv family. 💖 Go control that VPN, you've got this. ✨🦋💅

📦 where this page comes from