Skip to content

Hysteria. Managing the module ​

This article continues Hysteria quick start. If you haven't installed the module and created the first user yet, start there. Collected here are the operations on the module itself: starting and stopping the service, viewing logs, connection settings (the port and obfuscation), updating, reinstalling, and uninstalling. Managing VPN users is covered in a separate article — Hysteria. Managing users.

Page header and action menu ​

The page header exposes the core module actions — start, stop, and restart the service. The service state is shown by an indicator and a chip with the Hysteria version. The three-dot menu next to it groups the rest: open the logs, go to the module settings, check for updates, reinstall, or uninstall the module.

Hysteria module page header: state indicator, Hysteria chip, start, stop, and restart buttons, and the action menuHysteria module page header: state indicator, Hysteria chip, start, stop, and restart buttons, and the action menuExpanded Hysteria action menu with Logs, Module settings, Check for updates, Update Hysteria, Reinstall Hysteria, and Uninstall Hysteria itemsExpanded Hysteria action menu with Logs, Module settings, Check for updates, Update Hysteria, Reinstall Hysteria, and Uninstall Hysteria items

Managing the service ​

  • Start — brings the Hysteria service up from a stopped state.
  • Stop — shuts the service down. All active VPN connections are dropped, and new ones can't be established.
  • Restart — stops and starts the service back to back. Open connections are dropped.

Changes in the user list are applied by the server on the fly, without a service restart: a user added, disabled, or deleted — the change takes effect right away. The user's link stays the same — there's no need to add it to the app again.

⚠️ Stopping the service drops all VPN connections

While the service is off, no user can connect. Plan stops and restarts for a maintenance window or warn users in advance.

While the module is updating, being reinstalled, or being uninstalled, the service controls and the action menu are temporarily unavailable.

Module logs ​

In the action menu pick Logs — the lifecycle log opens with entries for install, update, reinstall, and uninstall. Each entry shows its status and the full execution output. Useful when an action ended with an error and you need to understand why.

Connection ​

In the action menu pick Module settings — the General page opens with a Connection group. This is where you change the parameters that devices use to reach the server: the port, obfuscation, and VPN users' access to the server's local network. If connecting over the current port has stopped working or the provider blocks QUIC, you can change the parameters without reinstalling the module.

The Connection group on the General settings page of the Hysteria module: Port field and Obfuscation toggleThe Connection group on the General settings page of the Hysteria module: Port field and Obfuscation toggle
  • Port — the UDP port Hysteria accepts connections on. It is set at install: 443 if the port was free, otherwise 2053. Valid numbers are 1 to 65535. Change it if the port is taken by another service on the server or if connecting over it has stopped going through. If the port is already taken by another BeAdmin module, a warning appears under the field. If an outside process holds it, the panel reports an error and keeps the old port.
  • Obfuscation — a toggle, off by default. Turn it on if your internet provider blocks QUIC or HTTP/3. With obfuscation on, the server no longer looks like an HTTP/3 site and doesn't show the maintenance page — how it works is described in Hysteria. How the service works.
  • Local network access over VPN — a toggle, off by default. While it's off, VPN users can't reach the server's local network: databases and internal services on its addresses stay closed to them. Turn it on if your team needs access to those services to work together. Services that are available only on the server itself (localhost) stay closed over VPN at all times, whether the toggle is on or off.

The Save button becomes active once you've changed at least one setting. The panel asks you to confirm a change of port or obfuscation — a safeguard against cutting off every user at once. The Local network access over VPN toggle is saved without confirmation. The service restarts and active connections drop, but the issued links keep working.

‼️ Changing the port or obfuscation drops all connections and invalidates the links

The port and the obfuscation parameters are baked into every issued hysteria2://… link and QR code. After you confirm, the service restarts, active connections are dropped, and every previously issued link and QR code stops working: client apps can't connect. Each user will have to be given the link again and add it to their app. Plan the change for a maintenance window and warn users in advance. If you return the old port and obfuscation, the old links work again.

Confirmation dialog for changing the Hysteria connection settings, warning that issued links will stop workingConfirmation dialog for changing the Hysteria connection settings, warning that issued links will stop working

If the service didn't start after a port change, check that the port you chose is free and pick another one.

Updating the module ​

You can check for updates and update the module from the action menu.

  • Check for updates — checks whether a new Hysteria version has been released. The check runs in the background, so you can keep using the page. You'll see the result in a notification. If an update is available, the notification includes an Update button.
  • Update Hysteria — appears in the menu once the check finds a new version. It lets you start the update even if you have already closed the notification.

Before the update, the panel shows a window with the version that will be installed and a warning: the module restarts during the update, and connected clients briefly lose their connection. The update starts once you click Update in that window; the new version is installed on top of the current one. The user list, the port, obfuscation, and the links are preserved — there's no need to add the link to the apps again.

While the update is in progress, the service controls and the menu items are unavailable; the current module version is visible on the Hysteria chip in the header. If there is no newer version, the panel tells you the module is up to date. If a newer version has been released that hasn't yet been verified for compatibility with the panel, the panel will tell you that too: such a version becomes available with a panel update.

Reinstalling the module ​

In the action menu pick Reinstall Hysteria. The panel asks you to confirm the reinstall — click Confirm. The module is installed again and the service restarts. The users, the port, and obfuscation are preserved, and issued links keep working.

Use reinstall when the module is acting up and you want to run the install again without losing users. Unlike uninstall, it doesn't wipe users or change links.

A reinstall keeps Hysteria on its current port. To move the module to a different port, enter it in the Port field of the reinstall dialog or change it in the Connection group. After the move, the issued links and QR codes stop working — the port is baked into them — and they have to be given to users again.

If clients stop connecting after a reinstall, copy the link again from the expanded user row or show the QR code again. If errors persist, the last resort is to fully uninstall the module and install it from scratch.

Uninstalling the module ​

In the action menu pick Uninstall Hysteria. The panel asks for confirmation: along with the module, the users and the settings are removed.

Hysteria uninstall confirmation dialog with a warning and the Confirm buttonHysteria uninstall confirmation dialog with a warning and the Confirm button

‼️ Uninstalling the module wipes all VPN users

Uninstall is irreversible: along with the module, all Hysteria users disappear — their passwords and hysteria2://… links. Apps that already have a link added can't connect after the uninstall. After a fresh install the users have to be created again: the links will be different, and each one has to be added to the apps again. The Hysteria licence slots are freed — you can reuse them or forget about the module until the next install.

After confirmation, the panel runs the uninstall. When it finishes, the module page returns to its initial state with the Install button.

What's next ​

BeAdmin © 2025. All rights reserved.