Frequently asked questions
Short answers; the README's Feature guide has the long ones.
Before you install
Will it break the sing-box, Xray or other panel already on the server?
No. m-ui runs its own sing-box core inside the m-ui process; it never installs, stops or edits a system-wide sing-box or Xray, their configuration files, or another panel. The only thing shared with them is ports — pick free ones for your lines (the new-line form already does) and they coexist.
Does it need Docker, Node or a database server?
No. The installer puts one static Go binary at /usr/local/bin/m-ui, an SQLite file at /etc/m-ui/m-ui.db and one systemd unit. No Docker, no Node, no nginx, no MySQL or PostgreSQL.
Exactly which files does the installer write?
/usr/local/bin/m-ui, the directory /etc/m-ui/ (database, cert/, backups/) and /etc/systemd/system/m-ui.service. Nothing else. Append --dry-run to the install command to print this plan for your machine without changing anything.
Will it conflict with nginx, Caddy or another web server?
Not by default: the panel listens on 2053, subscriptions on 2056, the reseller panel on 2054. Port 80 is only needed briefly if you issue a certificate with HTTP-01; use Cloudflare DNS-01 or a self-signed certificate if 80 is taken.
Does uninstalling delete my data?
Not unless you ask. install.sh --uninstall (or the SSH menu) removes the service and the binary and keeps /etc/m-ui, so installing again picks up your users, lines and certificates. Add --purge to delete the data directory too.
Can I try it without a server?
Yes. The live demo is the real panel interface running on sample data in your browser: no login, no backend, changes reset on refresh. It is built from the same frontend files as the release, so what you see is what you install.
Setup
Do I need a domain?
No. Certificate → Self-sign gives you TLS on the server IP in one click, and subscriptions automatically tell clients to allow the insecure certificate. A domain lets you issue a Let's Encrypt certificate and removes that warning — recommended, not required.
Which ports must be open?
Panel 2053/tcp, subscription 2056/tcp, reseller panel 2054/tcp if enabled, plus every line's port (TCP or UDP depending on the protocol). HTTP-01 certificate issuance also needs 80/tcp; Cloudflare DNS-01 does not. A node's panel port only needs to be open to the master's IP.
Can I change the panel port or path?
Yes, in Settings, or from the SSH menu (m-ui) if you locked yourself out. Paths work with or without the trailing slash. With port 443 (HTTPS) or 80 (HTTP), addresses and subscription links leave the port out; the panel and the subscription server can't share a port. Ports are validated before saving so the panel cannot restart onto a port already used by a line or another program.
What are the system requirements?
Linux amd64 or arm64 with systemd; Debian 11+ / Ubuntu 20.04+ recommended, Rocky / CentOS and other systemd distributions work too. The installer needs systemd, so Alpine (OpenRC) is not supported by it. Root for installation. The panel itself is happy on 1 vCPU / 1 GB. The platforms CI actually exercises are listed under Tested automatically.
Does it work on an IPv6-only server?
Yes: the panel, subscriptions and lines all listen on IPv6 and subscriptions give the IPv6 address (open IPv6 source ::/0 in your cloud firewall separately). Three things are limited: GitHub has no IPv6, so update checks and one-click updates need WARP installed on the Ops page first (updates then go through it automatically), and the install script cannot download either, so upload the package by hand; the direct egress cannot reach IPv4-only sites, so use WARP as the line's upstream for full access (common remote DNS servers clients use, such as 1.1.1.1, 8.8.8.8, 9.9.9.9 and 223.5.5.5, are redirected to their IPv6 addresses on direct lines automatically, so name resolution keeps working); the mainland reachability check is IPv4-only, with a separate IPv6 inbound check from probes abroad. On dual-stack servers subscriptions give IPv4 by default; set "Auto address uses" to IPv6 when editing a server.
Why does the new-line form already have a port?
It picks a free five-digit port that no other line, the panel or any other process on the server is using, and binds it once to be sure. You can change it; conflicts are rejected on save.
Users and subscriptions
The subscription shows my host name instead of the title I set.
Set Settings → Subscription → Profile title (resellers set theirs in their own panel). Clients like nextin and sing-box re-read it on every refresh. Shadowrocket and Clash Verge name a subscription when it is added and never rename it — use the landing page's one-tap import button (it carries the title) or have the user delete and re-add.
How is a device counted?
A full limit only refuses new devices; connected ones are unaffected, a slot frees up about a minute after another device goes offline, and refused connections show in red under Recent inbound connections on the Dashboard (the Refused filter shows only those). Devices are counted by distinct source IP, across all servers together, enforced centrally by the master. A phone on Wi-Fi and the same phone on mobile data are two IPs. IPv4 addresses and IPv6 /64s are counted separately and each must stay within the limit (over IPv6 the devices of one home connection share a /64, just as they share the router's address over IPv4), so a dual-stack device never counts twice.
Does renewing enable a user I disabled by hand?
Yes. Renewing, extending or changing a plan (Renew… and Change plan… in the panel, applying a plan to several users, /plan, /renew and /change in the external API) is an explicit activation: the user is enabled whatever the reason they were disabled, manual included, and the panel tells you before it runs. Assigning a plan only does not touch enabled/disabled; "Extend 30 days" re-enables users disabled for expiry but leaves manually disabled ones off. If someone should stay off, do not renew them.
Can I renew several months at once, and how is a plan change prorated?
Renew… takes 1–120 periods at once; enter 3 or 12 to sell a monthly plan quarterly or yearly. Change plan… offers three ways: replace (the new plan starts now and the rest of the old one is dropped), stack (the time left on the old subscription is kept and N periods are added; an expired subscription carries nothing over) and prorate (the value left is converted into time on the new plan using the reference prices you set on both plans). The dialog previews before and after and needs a confirmation for changes that cost the user. The external API does the same, with preview and de-duplication.
Can I put my own logo and links on the landing page?
Yes. Upload a logo under Settings → Subscription page (resellers: Account → Subscription page); it is live as soon as it is uploaded and gets a light backing in dark mode — a white logo on a transparent background is unreadable on both, so pick another. In the notice and the footer contact, text (https://example.com), [text](https://example.com), bare addresses and Tg: @username become clickable links; only http(s), tg, mailto and tel are recognised.
A kicked user's Hysteria2 / TUIC client is still connected?
Not any more. Kicking, disabling, deleting and re-keying close QUIC connections on the spot, the same as TCP ones. A client may still show "connected" while it tries to reconnect; a disabled user's reconnect is refused.
A user says they cannot connect. Where do I look?
Recent inbound connections on the Dashboard. If their IP is under the Connections filter they got in, and you can see which line. If it is under the Handshake failed filter, the certificate, password or SNI is wrong, and the Reason column says which. In neither: check the security group, firewall and client network first, but some failures are never recorded (Hysteria2 / TUIC QUIC handshake failures and a wrong obfuscation password, lines such as Shadowsocks and SOCKS, older nodes; hover the "?" next to the card title for the full list), so absence does not prove nothing arrived. Capturing packets on the server is the reliable check.
Can users share a subscription temporarily?
If you enable sharing, the landing page offers a temporary share link that uses a second credential set. Revoking it disconnects only the borrower, immediately, while the owner stays connected; usage, devices and expiry still count against the owner. The share link opens a trimmed landing page (import buttons, links, QR codes, nodes, your notice and purchase button) that never shows the owner's usage or expiry: the borrower opens it in a browser and imports it in one tap, or pastes the link straight into an app.
What do users see when their subscription runs out?
In a browser: their normal landing page with a status card on top (expired, traffic used up, or disabled — read from the panel), their links and QR codes unchanged, your notice and contact details, and a purchase / renew button if you set a purchase link (resellers can set their own). Only a link that matches no user gets the “invalid link” page. Clients get a plain 404 while the user is disabled.
Can subscription addresses avoid exposing user names?
Yes. Untick Settings → Subscription → Use user name as subscription URL; new users then get a random 32-character token. Existing users keep their current address either way.
Multi-server
Do nodes need their own certificate?
Yes, each node issues and renews its own (self-signed is fine). Lines are pushed with the master's TLS settings and each node serves them with its own certificate files. Nodes usually have no notifications of their own: the master alerts for their failed renewals and expiring certificates and flags them on the Servers page.
Which goes first when upgrading, the master or the nodes?
Upgrade the nodes first, then the master. Once the master uses a newer feature, a node that is too old rejects the whole sync and keeps serving its last configuration until it is upgraded: hiding and renaming external nodes needs v0.7.17 or later on the node; upstream groups, lines as upstreams and exclude keywords for external nodes need v0.7.16 or later; rule-based routing needs v0.6.14 or later; standbys for master failover need v0.7.17 or later on the node. With the nodes upgraded first, the first snapshot from the upgraded master is accepted everywhere. Nodes marked "Version differs from master" on the Servers page are the ones still to do.
Why do some external nodes in sing-box subscriptions now end in "2"?
Since v0.7.17, sing-box subscriptions, like Clash, get a latency-tested group for each line deployed on several servers; the group is named after the line, and the names and order of your own nodes do not change. Line names always stay with your own lines: a node in an external subscription that has the same name as one of the user's lines becomes "X 2" (in both Clash and sing-box subscriptions), even when the line gets no group this time (the user only has one server on it, or it is deployed on one server), so a client that picked the line group never silently lands on a third-party node. The rename happens once after upgrading and only changes the name, not the outbound settings; users who had picked that external node in their client need to pick it again. Give the external subscription a prefix to avoid clashes altogether.
What if the master goes down?
Nodes keep forwarding with the configuration they have, and connected users are not affected. Without master failover, subscriptions served by the master are unavailable until it returns; nodes can also serve subscriptions if you point users at them. With master failover turned on, a standby takes over as master; see the next question.
Can a node take over automatically when the master dies?
Yes: turn it on in the master's Settings → Master failover (off by default). The first few nodes in the server list (2 by default, 1–3) become standbys and keep a replica of the data: one every 5 minutes, and within 30 seconds of a change, encrypted to the standby's own public key and signed by the master. Pick one of three takeover modes: Off; Confirm, then take over (the default and recommended): 3 minutes after a standby confirms the master is unreachable it sends a Telegram message, and you reply with the code in it or click "Take over as master" on the standby's panel; Take over automatically when the master is lost: the standby takes over by itself after 10 minutes, which needs a majority of nodes to agree with three or more servers, and overseas probes that cannot reach the master either with one master and one node. The master being blocked from mainland China, one node losing its link, or the master upgrading or restarting does not count as lost. After taking over, the standby is the master; changes made on the old master after the last replica, a few minutes of traffic on the old master's own lines and the traffic charts cannot be recovered. When the old master comes back it turns into a node by itself. Every node must run v0.7.17 or later; nodes linked over plain http are not used as standbys by default (a man in the middle on that link could read and rewrite the replica), and you can allow them under Advanced if you trust the link. Over SSH: m-ui ha status shows the state, takeover takes over on a standby, set-master makes a node the master, and pause / resume pause and resume takeovers around upgrades and maintenance.
What is the easiest way to move the master to another server?
Use Set as master. Install m-ui on the new server, add it like any node, and once it shows "synced", click its role tag on the Servers page (such as "Node ▾") → "Set as master" and enter the admin password once. All of the master's data is encrypted end to end and handed over; the new server becomes the master and the old one turns into a node, with no backup or restore, and your account and password stay the same. Writes pause during the handover, usually for a minute or two; both servers restart once and users connected to them reconnect after a few seconds. If the link to that server is plain http, you must tick a risk acknowledgement first (an active man in the middle on the link could read and rewrite the whole database); switch to https first if you can. Set as master does not promise that every byte gets counted: traffic on these two servers' own lines during that minute or two is not counted towards users' usage, while the other nodes' traffic is recovered as usual.
What happens if I restore the master's backup on another server?
Once restored and started, that server becomes the master: it takes over every node with a higher epoch, and if the old master starts again later (for example after the provider reboots the VPS) it turns into a node instead of fighting over the role. So if you only want to look inside a backup, do not restore and start it on a machine that is online. When you no longer need the old server, run systemctl disable --now m-ui on it. While the old master is still running, Set as master (previous question) is simpler.
The master changed. How does the subscription domain follow?
The subscription domain, port and path move with the master, so point the subscription domain's DNS at the new master; the new IP is shown at the top of the page and in the Telegram message. If the domain is on Cloudflare, you can turn on automatic DNS updates under Master failover → Advanced (off by default): create a separate token that can only edit this domain's DNS (Cloudflare dashboard → My Profile → API Tokens → Create Token, use the "Edit zone DNS" template and set Zone Resources to "Include → Specific zone → your domain"; the "Create one on Cloudflare" link under the field opens the creation page with the permissions filled in), kept apart from the certificate token. From then on, when the master changes only the A / AAAA records pointing at the old master's IP move to the new one, with proxy status and TTL untouched; if that fails you get an alert listing what to change by hand. If subscription addresses use an IP, users have to re-import their subscription after the master changes, so switch to a domain first.
What happens when a node goes offline?
The master marks it offline on the Servers page (and sends a Telegram alert if you configured the bot); the other servers keep working. Lines that live only on that node are unreachable until it returns. On reconnect the master pushes the full snapshot again and continues the traffic counters from the stored cursor, so nothing is double-counted.
Is traffic double-counted when a node reconnects?
No. Nodes keep monotonic counters and the master stores a cursor per node, so only the delta is added. See Multi-server.
Resellers
The new reseller cannot log in.
A new reseller has no password. On the reseller panel they enter the name, leave the password empty and click Log in; the panel then asks them to set one. The first-login window can be reset from the master.
Can a reseller see my users or lines?
No. Resellers see only their own users and plans and only the lines you granted. Scoping is enforced on the server, not in the UI.
Operations
How do updates work? Will I lose data?
The sidebar shows an arrow when GitHub has a newer release. One click downloads the archive, verifies it against the release's SHA256SUMS, replaces the binary and restarts. The database, certificates, backups and settings are untouched. The installer does the same when run again. Since v0.4.9 every update is a transaction: the previous binary is kept, a pre-upgrade backup is written first, and if the new version does not answer within 90 seconds the previous binary (and, if needed, that backup) is restored automatically and the panel tells you so.
What is in a backup?
The database (checkpointed so it is consistent) and the certificate files, as one zip, including certificates outside the data directory that settings point to (one issued by certbot, say). Restore from the panel; the migration wizard moves a whole installation to a new server.
What happens to certificates after restoring on a new server?
A certificate from outside the data directory keeps using the file at its original path if the new server has a usable copy of the same certificate there; otherwise the backed-up copy goes to /etc/m-ui/cert/restored/, settings are pointed at it and the panel tells you once at the top. Nothing like certbot renews those copies, so issue them again on the certificate page, or add them again after installing the original tool on the new server. If the panel, subscription or reseller-panel certificate is still missing, a temporary self-signed certificate keeps the service up with a warning; while it is in place clients report a certificate error when they refresh the subscription, so replace it as the banner says.
Is there a manual inside the panel?
Yes. Help in the top-right corner (left of Feedback / Support) opens the built-in manual in a new tab at the chapter for the page you are on, with a table of contents and in-page search; the reseller panel opens the reseller view. It ships with the binary and works offline.
Can I migrate from a legacy panel?
Yes — the importer reads the compatible legacy database format and keeps ports, credentials, panel path and subscription addresses, so existing clients continue without a refresh. Run the installer with --import /path/to/old.db, or use Users → Import to move only users.
Does m-ui send any telemetry?
No. m-ui has no telemetry and collects no usage data. Outbound connections are the ones you configure (ACME, Cloudflare, WARP, Telegram), a version check against GitHub Releases every 6 hours, and the supporters list and online panel count: reading a public list when the Feedback page is opened and one daily download of an empty file from GitHub, with no identifier. One switch in Settings turns those two off.
Where do I ask questions or report bugs?
Questions and ideas: GitHub Discussions. Confirmed bugs: an issue using the form. Please redact tokens, UUIDs and subscription URLs from logs.