m-ui HelpReseller panel help
Find a feature in the contents (on a phone, tap “Contents” at the top right), or use the search box above. Text in grey boxes matches the buttons and titles in the panel exactly, so you can look for it and click it. This view only covers what the reseller panel can do.
Getting started
m-ui is a self-hosted proxy panel: lines, users, subscriptions, certificates, backups and multiple servers, all managed in the browser.
The reseller panel manages the users under your account: create them, renew them, watch their usage, and send them their subscription links.
A few words first
These ideas come up everywhere in the panel; knowing them makes the rest easy.
- Line: the entry clients connect to, a protocol plus a port, and where its traffic leaves from. The nodes in a user's subscription are generated from lines.
- Upstream: the exit of a line. The default is direct (straight out of this server); it can also be WARP or another exit server.
- User: one subscription link with a traffic quota, expiry, device limit and speed limit. Running out of traffic or expiring disables it automatically; a full device limit only refuses new devices, and the speed limit only slows it down.
- Plan: a template of quota, duration, devices, speed and lines, applied in one click when creating or renewing a user.
- Subscription: the link clients import; opened in a browser, the same link shows the user's own landing page.
- Master / node servers: the master holds all data and does the accounting; nodes only forward traffic and get their configuration from the master.
- Reseller: someone who sells accounts for the site owner and only manages their own users in their own reseller panel.
First sign-in
Open the panel in a browser after installing, and change the default password first.
- Open
http://SERVER-IP:2053/app/(use the port and path printed at the end of the installation). - Sign in with the default account
admin/admin. - A red bar at the top warns about the default password. Click Change now; on the Admin page, under Login account, fill in Current password and New password, click Update account, then sign in again with the new password.
- Opening just
http://SERVER-IP:2053/gives a 404 on purpose: the panel path is not revealed to port scanners. Always include the full path. - The page does not load: check that the cloud security group / firewall allows 2053/tcp.
- Forgot the address or password: SSH into the server and run
m-ui; option 1 shows the panel address, option 5 resets the admin password.
Five steps to go live
The Quick start checklist on the dashboard is exactly these steps; after the first four you can hand out accounts.
- Change the default password (see above).
- Get a certificate: Certificate page → Add a certificate. With a domain, choose Domain (auto-issue); without one, choose No domain (self-signed) and click Generate self-signed. See Certificates.
- Create a line: Lines page → Quick add; beginners pick Hysteria2 or AnyTLS and save. See Lines and protocols.
- Create a user: Users page → Add user; fill in a name and the quota, tick the Lines they may use, save.
- Send the subscription: click the user's name to open the details. Under Subscription there are two links; send the one without
?format=(the universal link): in a browser it opens the user's own landing page with one-tap import, and apps get the right format when they fetch it (see Subscription links, QR codes and sharing).
https://DOMAIN…, the old links stop working at once and every client must re-import; you are asked once more before issuing. Leave it unticked to keep the old links, and users just refresh their subscription once.Reseller: three steps to start
Once the site owner has created your reseller account, these three steps get you selling.
- Open the reseller panel address you were given (default port 2054, path
/dl/). Enter your reseller name as the username; on the first sign-in leave the password empty and click Sign in, then set a password when asked. See First sign-in and password. - (Optional) Create a few plans on the Plans page so new accounts and renewals take one click.
- On the Users page click Add user: enter a name, choose a plan or fill in the quota, tick the Lines, save. Click the user's name to open the details and send them the link under Subscription that has no
?format=.
Finding your way around
Navigation is on the left, help and feedback are at the top right; things that need you are collected in Needs attention at the top of the Dashboard, and coloured bars at the top of other pages remind you too.
- The navigation, top to bottom: Dashboard, Lines, Upstreams, External nodes, Users, Resellers, Plans, Rules, Servers, Certificate, Backup, Ops, Logs, Admin, Settings.
- Bottom left: theme (◐ follow the system, ☀ light, ☾ dark), language and Sign out. An arrow next to the version number means an update is available; click it to update (see Updating).
- Top right: Help (this page) and Feedback / Support (contact the author, report problems).
- Needs attention: a failed data-plane reload, servers offline or not synced, certificates needing attention, mainland reachability problems, failing upstreams, users about to expire or run out of data, a failed scheduled backup and so on, one row per kind, most serious first, each with a link to fix it; when everything is fine only a single "✓" line remains. Certificate and reachability rows have Got it; they come back when the situation changes.
- Reminder bars at the top: on pages other than the dashboard, a default password, certificates needing attention, mainland reachability problems, a failed data-plane reload and so on are shown at the top of the page. Follow the hint.
- On a node server's own panel, pages such as lines and users are read-only; make changes on the master.
- Shortcuts: / jumps to the page's search box, Esc closes dialogs, Ctrl + Enter submits a dialog. On a phone, tap ☰ at the top left to open the navigation.
Servers: master and nodes
One master server holds all the data; any number of node servers can be added as extra entry points. Each line appears once per server in subscriptions, and clients pick the fastest.
Do I need nodes?
One server is enough to start; add nodes when you want more regions or more entry points.
- Every 5 seconds the master pushes lines and users to the nodes and collects their traffic and online devices; quotas and expiry are judged on the master only.
- Nodes only forward traffic. If the master is unreachable for a while, nodes keep serving with the last configuration they got; traffic is reconciled afterwards and never billed twice.
- Add a server and every user's subscription gains the matching nodes automatically.
Attach a node
Install m-ui on the node and enter its pairing details on the master.
- Install m-ui on the node server the same way and sign in to its panel (change the default password first).
- On the node: Settings → Role, tick Run as node (secondary server) and click Save.
- On the node: Settings → Pairing, copy the API URL and the Pairing token.
- On the master: Servers page → Add server. Enter a Name (it becomes the suffix of node names in subscriptions, such as "HK"), the API URL and the pairing token. If the node's panel uses a self-signed certificate or a bare IP, tick Skip certificate verification.
- A few seconds after saving the row should show synced.
- With an
http://API URL the token and every user's credentials travel in plain text; the row is marked Plaintext. Give the node's panel HTTPS (self-signed is fine), or allow its panel port only from the master's IP. - Each node issues and renews its own certificates on its own Certificate page.
- Once a node's panel switches to HTTPS (Use for panel HTTPS ticked on the node's Certificate page; it applies after a restart), edit its row on the master's Servers page and replace the API URL with the new
https://one from the node's Pairing (tick Skip certificate verification for a self-signed certificate or a bare IP); otherwise the node shows offline. That option is ticked by default when you issue a real certificate on a node; untick it if you do not want to change the API URL. - On a node's panel, lines, users and plans are read-only; make changes on the master.
- Keep master and nodes on the same version: when a row says version differs from master, update the node. Once newer features are in use, a node that is too old refuses the whole sync and keeps serving the old configuration: rule-based routing needs v0.6.14 or later; lines as upstreams, upstream groups and excluded keywords on external nodes need v0.7.16 or later; hiding and renaming external nodes needs v0.7.17 or later.
Connect address, IPv4 and IPv6
By default subscriptions use each server's detected public IP, with the domain used only as SNI, so a poisoned DNS on the client cannot break the connection.
- Edit a server → Connect address (IP allowed): leave it empty to use the detected public IP, or enter a fixed IP or domain.
- Auto address uses: dual-stack servers give IPv4 by default and can switch to IPv6; if the chosen family was not detected, the other one is used. A manual connect address ignores this setting.
- On dual-stack servers each line can also pick its own IP version in the line form.
- To put the domain instead of the IP into subscriptions: Settings → Subscription → Node address in subscriptions, choose domain. First fill in Domain / IP for every server (empty on this server = the panel domain): in this mode the Connect address (IP allowed) is ignored, and servers without a domain are left out of subscriptions.
::/0 or the server's own firewall blocks IPv6. Only one port per server is checked, so open every other port as well; UDP lines (hysteria2, tuic) cannot be checked this way, capture packets on the server to confirm.- Cloud IPv6 needs its own security-group rules for
::/0(separate TCP and UDP rules); ip6tables / ufw on the server must allow it too. Flushing iptables does not open IPv6. - Outbound-only IPv6 (WARP, NAT and the like) cannot be used by clients to connect.
- IPv6-only servers: install WARP before checking for updates (see WARP). Direct exits cannot reach IPv4-only sites; choose warp as the line's upstream to reach the whole internet.
Traffic ratio
Charge more for an expensive server: traffic through it counts towards users' quotas with a multiplier.
- Edit a server → Traffic ratio:
2counts double and adds anx2tag to node names;1counts as is. The master can have a ratio too. - Users' usage, the chart in their details and the numbers on their landing page all use the converted figures, so they add up; line and upstream statistics show actual traffic.
Mainland reachability
Find out whether a server is blocked in mainland China: home-broadband probes of China Mobile, China Telecom and China Unicom connect to it, with Hong Kong probes as a control.
- The Mainland reach column on the Servers page shows the result. Click a cell for details, or Check mainland reach to test every server.
- Reading the result: OK; Partly down (one carrier cannot connect); Likely blocked; IP blocked (change the IP); Port blocked (change the port); Down abroad too (a server, port or security-group problem, not a block).
- Scheduled checks: Settings → Mainland reachability → Automatic checks, on by default: the first round runs about 2 minutes after m-ui starts, then every 90 minutes by default, with a Telegram alert when a server gets blocked or recovers.
- The server address (IP and port) is sent to the public Globalping network, by the automatic checks too; if you do not want that, untick Automatic checks and only check by hand when needed. Without an account you get about 250 probe runs per hour and one server uses about 15; if that is not enough, add a free Globalping token (optional) in the settings.
- The check uses the port of the server's first TCP line; with only hysteria2 / tuic (UDP) lines it can only tell whether the IP is blocked. Only IPv4 is checked for now: most mainland home-broadband probes have no IPv6, so testing IPv6 from them would report healthy servers as blocked (see Known limitations).
Disabling, deleting and offline nodes
Disabling or deleting a node stops it serving right away; when a node shows offline, start with the reason shown in its row.
- Edit a server and untick Enabled: it immediately stops serving everyone; enable it again to resume.
- Deleting a server disables lines that were deployed only there, and users or resellers that only used it lose that line; the affected lines and people are listed afterwards.
- shutdown notice pending: that machine has not yet received the notice to stop serving; the master keeps retrying. To stop it at once, SSH in and run
systemctl disable --now m-ui(stops it and keeps it from starting at boot), or uninstall with option 14 of them-uimenu. Turning off node mode does not stop it: the machine becomes a standalone master and keeps serving everyone with its last configuration. - Offline reasons: connection timed out, connection refused (port not open or panel not running), DNS lookup failed, certificate not trusted (tick skip certificate verification), token mismatch (copy the pairing token again), Certificate fingerprint changed (if you really re-issued the node's certificate, open More on that row and click Reset fingerprint).
- Replacing a node: install the new one, then edit the old row on the Servers page with the new API URL and token; the master pushes everything again. If the domain and API URL stay the same (the domain already points at the new server), changing just the token is enough: the master treats it as a new server and drops connections still open to the old one, so pushes, reports and the cross-server device count all go to the new server right away. With Skip certificate verification on, the remembered fingerprint is dropped together with the old token and learned again on the first contact with the new server, so there is no need to click Reset fingerprint.
Set as master and master failover
Two things: Set as master moves the master to another server in one go (planned moves and moves to a fresh VPS both use it); Master failover lets a standby take over as master when the master dies (VPS down or deleted by mistake). Failover is off by default.
Set as master
From the master's panel, make any node the master: the data is handed over in one go and the old master becomes a node.
- On the Servers page, click the role tag at the start of that server's Status column (e.g. "Node ▾" or "Standby 1 ▾") and choose Set as master in the card that opens; the ⋯ (More) menu at the end of the row has it too.
- The dialog spells out what will happen: the checks, the new panel and reseller panel addresses, and which IP the subscription domain's DNS should point to. Enter the admin password once (plus the two-factor code if enabled).
- Progress is shown throughout, and the new panel and reseller panel addresses are given at the end. Account, password and two-factor stay the same; sign in again on the new panel.
- All master data (users, lines, plans, resellers, settings, traffic history) is handed to that server end-to-end encrypted and it becomes the master; the old master becomes a node and keeps serving with its own lines. Both servers restart once; users on them reconnect after a few seconds, other servers are not affected.
- If any step fails before the commit (including a transfer so slow it gets close to the deadline), it is cancelled automatically: the old master stays master, changes are allowed again and no data changes.
- Moving to a fresh VPS: install m-ui as usual, add it like a node (see Attach a node), and once it shows synced, use Set as master on it — no backup and restore needed.
- If the link to that server is plain http, the dialog only lets you go ahead after ticking I understand the link to it is plain http and an active attacker on the path can read and rewrite the whole database; go ahead anyway. Switch to https first if you can (a self-signed certificate with a fingerprint works too).
- The subscription address stays the same: the subscription domain, port, path and certificate move with the master, so just point the subscription domain's DNS to the new master. If the subscription address uses an IP, or the subscription port that moves over equals that server's panel / reseller panel / WARP port or a line port, it keeps its own subscription port and the subscription address changes; the dialog's Note says so beforehand. The panel and reseller panel use the new master's own addresses.
- If the subscription certificate is an Existing certificate (renewed by certbot or a similar tool) and the new master has no certificate of the same name, what moves over is a copy that nobody renews there: afterwards, reissue it on the new master's Certificate page, or install certbot there and add it again.
- A server that is offline, disabled, not synced, too old, short of disk (on it or on this server), unable to reach this server, or when this server's address as a node cannot be built, cannot be set as master; the card says why. If its reseller panel port is taken by a line there, the reseller panel will not start once it is master; the Note lists that too.
- Traffic on both servers' own lines during the handover is counted: from the moment changes are paused the old master also keeps a separate ledger, and once it becomes a node the new master collects what came after packing; what the target records after receiving the data is merged in when it switches to the new database; traffic on the other nodes' lines is recovered as usual.
- Changes are paused during the handover, usually for a minute or two and at most for a limit worked out from the database size (15–60 minutes), shown in the progress dialog and at the top of the page: the panel is read-only, and the external API, the reseller panel, the Telegram bot and temporary shares on the subscription page return 503, so integrations should retry.
- If the commit request gets no reply, the progress dialog shows an unknown result: changes stay paused and the old master asks the target every 10 seconds. If there is still no answer by the deadline, or you click Give up (fence off the target) and enter the password again, the old master first asks the target once more and checks which master the nodes follow: if some nodes already follow the target, the change is completed; otherwise it stays master with a higher epoch and changes resume, and even if the target comes up later, the nodes no longer follow it, it becomes a node by itself and its copy of the data does not take effect. Fencing needs the nodes to confirm the revocation: giving up before the deadline needs every node other than the target, after the deadline a majority is enough; until then changes stay paused and it completes by itself once unreachable nodes come back.
How master failover works
Turn it on in the master's Settings → Master failover (saving asks for the admin password). The first few nodes in server order become standbys and keep an encrypted data replica.
- Standbys defaults to 2 (1–3), picked in the order of the Servers page and marked "Standby 1", "Standby 2"; reordering changes who takes over first. If a front standby is briefly offline or short of disk, it keeps its place for 30 minutes before the next one moves up; a newcomer on the list is announced on Telegram.
- The master sends the replica to the standbys regularly (every 5 minutes by default, plus one within 30 seconds of a change). It is encrypted to the standby's own key and signed by the master, and only opened on takeover. If sending keeps failing, the card and the Readiness check show the reason.
- While the master is lost, nodes keep forwarding and connected users are not affected; a takeover restores management, billing, subscriptions and alerts.
- After a takeover it is the master and can stay so. Traffic on the nodes' lines is recovered automatically. What cannot be recovered: admin changes made on the old master after the last replica and a few minutes of traffic on the old master's own lines. Traffic history (the dashboard and landing-page charts, per-day traffic in the external API), subscription logs and audit entries older than 7 days travel separately to the standbys as "history data" about once an hour and are carried over on takeover, so the charts miss at most about the last hour; if the standby has not received it yet, these start empty (the takeover notice says so). Nothing is merged back when the former master returns.
- The Readiness check on the settings page ticks each item: eligible standbys, node versions, replica self-check, whether the links to the nodes are https, whether the subscription uses a domain, Telegram, node-to-node connectivity, the overseas witness; anything that fails comes with a one-line fix.
- A standby's card shows its key fingerprint, which should match the one shown under Settings → Master failover on that node.
- Every node must run v0.7.17 or newer: older ones keep syncing but cannot be standbys. Upgrade the nodes first, then the master: standbys older than the master keep their place and their old replica but get no new replicas, and you are alerted once when there are too few eligible standbys.
- A node on a plain-http link is not a standby by default: an active attacker on an http link can read and rewrite the data replica. If the path is really trusted, turn on Allow nodes on plain-http links as standbys under Advanced.
- Nodes need each other's panel port open so they can confirm with each other whether the master is really lost; otherwise only the overseas probes or a person can decide.
- If a standby reinstalled m-ui its key changes: click Trust again in its card, check the fingerprint and enter the admin password again before it gets replicas again. If the fingerprint does not match and it was not reinstalled, someone may be impersonating it.
Takeover modes
Pick one of three when you turn failover on; the default is Confirm, then take over.
- Off: if the master dies a person has to act; nodes keep serving with their own lines.
- Confirm, then take over (the default, recommended): 3 minutes after the standby confirms the master is lost it sends a Telegram message; reply with the
/takeover CODEit gives, or click Take over as master in the standby's panel, and it takes over. The button only appears once the confirmation has been sent; before that, or when the evidence is not enough, the top of the standby's page says why it does not take over. If the master comes back first, the request is cancelled. - Take over automatically when the master is lost: 10 minutes after the master is lost the standby takes over by itself. With three or more servers a majority of nodes must agree; with one master and one node the overseas probes must not reach the master either, so Overseas probe witness must be on. This mode has no takeover button; to force a takeover anyway, run
m-ui ha takeover --force. - What counts as lost: the standby has heard nothing from the master for over a minute, other nodes cannot reach it either, and the overseas probes (US, DE, JP, SG, HK) cannot reach its public IP. A block from mainland China, a cut between one node and the master, or a master upgrade or restart does not count.
- Split-brain protection: every takeover or Set as master moves to a higher epoch and nodes follow only the highest. The state the master pushes to nodes is signed, and the handover carries an expiry and is bound to the new master's key, so a node token alone cannot forge one.
- How long to wait before confirming or taking over automatically, and the replica interval, are under Advanced.
- Before upgrades or maintenance you can pause takeovers (the pause buttons on the settings page, or
m-ui ha pause MINUTESon the master). Actions in the panel that restart (upgrade, changing ports), and the upgrade (15-minute pause) and restart (5-minute pause) in them-uimenu, pause first automatically. - Without Telegram alerts, confirm mode can only be triggered from the standby's panel.
- If the subscription address is an IP, users have to import the subscription again after a takeover. Use a domain for the subscription; to keep the subscription address after a takeover, choose Subscriptions too below.
- If a standby's replica is older than its current epoch (changes made under the previous new master are not in it), it gets no takeover button; to take over anyway run
m-ui ha takeover --force, and those changes are lost.
When the old master comes back
The old master becomes a node by itself when it recovers; it does not fight the new master.
- In the new master's server list it is first marked "Former master · lost" and kept out of subscriptions; when it is back it turns into a "Node", gets the configuration again and its lines return to subscriptions.
- If it took changes while lost, it keeps a backup before becoming a node, and the top of the page says how many changes did not reach the new master.
- If a standby took over while the master was in fact still there (a network partition, say) and most nodes still follow the old master, it hands the master role back and puts back the DNS records it changed; the notice says it handed back rather than lost contact.
- To make it the master again, use Set as master on it in the server list.
Backups, restores and moving servers
The epoch only goes up: restoring an old backup on the master, or "Reset all settings" in the menu, does not move it back; nodes keep following, and the top of the page says once that the epoch was restored.
- Restoring the master's backup on another machine and starting it moves the master to that machine: the new machine takes over all nodes with a higher epoch; if the provider later restarts the old master, it becomes a node by itself and says "the same data is running as master on another server". If you no longer need the old machine, run
systemctl disable --now m-uion it. - If you only want to look inside a backup, do not start it on a networked machine.
- Deleting a node, or Rotate token on the node, clears its failover records so another master can add it. A node deleted while offline is cleared when it comes back.
- Before moving the master back to 0.7.16 or older, run
m-ui ha reseton every node; otherwise the old master cannot manage nodes that have entered an epoch.
What a takeover moves over: master duties only, or subscriptions too
Under Master failover, What a takeover moves over has two choices; Master duties only is the default.
- Master duties only: pushing configs to nodes, merging traffic, expiry / quota cut-offs, the Telegram bot and the external API move to the new master; its own subscription settings stay as they are and DNS is untouched. Subscription addresses still point to the former master: while it is down, refreshing subscriptions fails (connected lines keep working), and once it comes back as a node it serves subscriptions again. The subscription certificate (and its private key) does not travel to standbys either.
- Subscriptions too: the new master also takes over the former master's subscription domain, port, path and certificate, and the DNS interface points the subscription domain to it, so users keep their subscription address. It needs a domain in the subscription address and a DNS provider interface; saving tells you what is missing. When the panel uses a domain, the panel and reseller panel addresses (the external API lives on the panel) move over too: the new master takes the former master's panel domain, port, path, certificate and trusted proxies, and the panel domain is pointed to it as well, so shops, bots and resellers using the external API need no changes; API keys, permissions and allowlists are in the data replica anyway. A panel on an IP can't move, and the readiness check suggests giving it a domain.
- Set as master (a planned move) is not affected by this choice: subscriptions always move with it and the subscription certificate travels with the full data; with a DNS interface and the subscription domain in the list, DNS is updated automatically, otherwise the dialog says which IP to point it to.
- DNS providers: Cloudflare (an API token, see Creating a Cloudflare API token), Alibaba Cloud DNS (the AccessKey of a RAM user with only AliyunDNSFullAccess) and Tencent Cloud DNSPod (the API key of a sub-user with only QcloudDNSPodFullAccess). Credentials are stored on their own and never shown again. Test the DNS interface and records lists the records that would change; wrong credentials or a domain outside the account are reported right there.
- Subscription certificate: when subscriptions use https, standbys carry the master's subscription certificate in the encrypted replica. If it can't be used at takeover (missing, expired, expiring within two weeks, or not covering the subscription domain), the new master issues a new one for the subscription domain through the same DNS interface (DNS validation doesn't wait for the record to move), uses it for subscriptions and restarts the subscription service in place; later renewals use that interface too. The readiness checks show how many days the subscription certificate has left.
- Only A / AAAA records among the Names that follow the master (the subscription domain is added automatically) that point to the former master's IP are changed; line, TTL and proxy status are kept and other records are untouched. A failure only alerts and doesn't block the change. The outcome is all done, partly done or failed; the top of the page and Telegram list each record's old → new value and anything left for you to change by hand.
- When a standby that took over by mistake hands the master role back, records it changed that still point to it are put back.
- In a cluster that has used failover (epoch 1 or higher) a node can't be switched to master on its panel: the other nodes only accept a master with an epoch and would reject it. Use Set as master, or let a standby take over if the master is gone; to really leave the cluster, run
m-ui ha reseton every server first. Switching the master to a node is fine and clears its local failover state. - With master failover on, ports a node needs after taking over cannot be used by lines or relay entries on it: its own reseller panel port (nodes don't listen on it until they take over), and with Subscriptions too also the master's subscription port (it moves over). Existing clashes block turning failover on and are listed by name, and saving a line or changing the subscription port is checked too; UDP-only lines (hysteria2, tuic) don't clash. Each server keeps its own panel port after a takeover, so that one doesn't need to be avoided.
- Ports taken by other programs (m-ui's own lines avoid them, but other programs can't be stopped): standbys try the ports they need after a takeover every 10 minutes, and taken ones are listed in the Readiness check with one Telegram message. If a port is still taken at takeover time, the new master first falls back to its own previous port (usually already open in the cloud firewall), and only then picks a free port, so it always starts; the notice and Telegram give the actual address and remind you to open the new port in the cloud firewall / security group.
- Two masters at once: if a standby that took over cannot reach the other nodes (say their firewalls only allow the former master's IP), most nodes still follow the former master when it comes back, and both keep acting as master, so subscriptions and changes diverge. Needs attention turns red on both and Telegram gets one message. To keep the former master, click Hand back master on the new one (or run
m-ui ha yield): it becomes a node and puts back the DNS records it changed. To keep the new master, open the firewalls so it can reach the other nodes. The readiness check on node-to-node connectivity warns about this beforehand. - When a set-master ends with an unknown result (the target went silent after the commit request), writes stay paused: until the freeze deadline this server asks the target every 10 seconds; after it, it checks whether any node follows the target and, if none does, fences the target off with a higher epoch and resumes writes. That needs the other nodes to confirm the revocation (all of them before the deadline, a majority after). If the unreachable nodes are gone for good and there is still no majority after the deadline, run
m-ui ha abandon --forceon the master; not before the deadline, since nodes that missed the revocation hold a handover mark that stays valid until then. - The environment variable
M_UI_TEST_CF_APIpoints the DNS provider's API at a test address, for drills and tests only; when it is set the settings page says so and the audit log records it.
Command line
Over SSH, use m-ui ha (root required); item 15 of the m-ui menu is master failover too.
m-ui ha status: this server's role, epoch, mode, standbys, replica time and key fingerprint; it gives a rough picture even with the service stopped.m-ui ha takeover: take over as master on a standby; refused when the evidence is not enough.--forceskips the confirmation and the evidence; use it only when you are sure the master is gone. On a master,--forcereclaims nodes that followed another master, with an epoch above the highest one known; use it only when two masters are deadlocked.m-ui ha set-master NAME-OR-ID: on the master, make a node the master and print the new panel address when done; an http link needs--allow-plain. With an unknown result it prints the reason and the latest deadline.m-ui ha pause MINUTES/m-ui ha resume: pause / resume takeovers on the master.m-ui ha reset: clear this server's failover records (epoch, followed master, replicas) so another master can add it; on a master it needs--force.
Lines and protocols
A line decides how clients connect: inbound protocol + port → where the traffic leaves. Each line appears once for every server it is deployed on.
Create a line
Quick add is the easiest start: the protocol settings are ready and a free port is picked for you.
- On the Lines page, click Quick add at the top right and pick a preset: Hysteria2, AnyTLS, VLESS + Reality, Trojan, Shadowsocks 2022 or VMess + WS.
- The form is filled in; check the Name (the node name shown in subscriptions) and the Port, then save.
- To configure everything yourself, click Add line: choose the Protocol and a port; the Upstream defaults to direct (straight out of this server).
- New lines have Assign to all existing users (not resellers' users) ticked. If you untick it, the line only shows up in subscriptions after you tick it for each user.
- A free five-digit port is filled in for you and can be changed; a clash with the panel or subscription ports, or with another program on the server, is rejected when you save.
- Before saving, the whole configuration is test-run by the core; if it fails nothing changes and running lines are untouched. Changing a line restarts the data plane briefly, and online users reconnect by themselves.
Line traffic and who is online
- On Lines, click a line's name or Details. The four boxes at the top show the line's total traffic for the chosen range, how many servers it runs on, and how many users and IPs are on it right now.
- The Traffic chart starts with All servers combined and switches between 24h / 7d / 30d. Pick a server in the drop-down, or click its row under Per server, to see only that one; click the row again to go back to the total.
- Online users & IPs refreshes every 5 seconds and shows which server each person is on and from which IPs. With many people you can search; 40 are shown at a time, and a name takes you to Users.
- A node keeps its own line traffic, so it is fetched when you open the details. Servers that can't be reached, are disabled or run a version that is too old are marked in the list and left out of the total.
- Line traffic is the bytes that actually went through each server; server traffic ratios aren't applied, so it need not add up to the users' usage.
Relay entries: letting users come in through another machine
Use this when users' direct connection to this server is slow or blocked (say, routes from mainland China to an overseas machine, or an IP that got blocked): they first connect to a machine with a better route (another of your servers, or a relay you bought), which passes the traffic on to this one as is. The data goes "user → relay → exit (this line's server) → website". The relay only moves data and can't decrypt it. Leave it off if you don't need it.
- Edit the line and tick Relay entries (off by default); unticking and saving clears them.
- Each entry reads as a sentence: Users connect to which relay, which port, forwarded to which exit (the address and line port it forwards to are in brackets). Pick another of your servers as the relay and it does the forwarding automatically; a free port on it is filled in, trying the line's own port first.
- For your own realm / iptables forwarder or a relay you bought, choose A relay elsewhere (enter address) and enter its address and port (pasting "address:port" splits them); the line below says what traffic on which port to forward where.
- The second line shows the Node name in subscriptions on the left (you can edit the relay part) and what to do on the right (which port to open in which firewall). Port clashes on the relay server (its panel / subscription, lines running there, other relays) turn red at once and block saving.
- If the two servers share a private network, click the address in brackets to use a private one; tick Paused to keep an entry without using it. In the line list, "⇄ N" after a line's name counts its relay entries; the line details list them at the top.
- Open the port in the relay server's firewall (your cloud provider's security group): UDP for hysteria2 / TUIC, TCP and UDP for shadowsocks, TCP for the rest.
- The exit server sees the relay's IP: several devices of one person coming through the same relay count as one IP there, so device limits can't hold back devices on a relay; relay IPs show "⇄ server name" among online IPs.
- Relay nodes don't carry port hopping; traffic is counted at the exit server's ratio as usual. Deleting a server removes the relay entries that go through it or forward to it.
Choosing a protocol
Not sure? Use Hysteria2 as the main line and add one TCP line (AnyTLS or VLESS + Reality) as a backup.
| Protocol | Runs on | Certificate | Strengths / best for |
|---|---|---|---|
| Hysteria2 | UDP | Required (self-signed works) | Fast and resilient to packet loss; the first choice. Add port hopping if your ISP throttles UDP. |
| TUIC | UDP | Required | Same family as Hysteria2 (QUIC-based); an alternative. |
| AnyTLS | TCP | Required | Weak traffic fingerprint; the first TCP choice when UDP does not work well. |
| VLESS + Reality | TCP | Not needed | No domain or certificate; borrows a big site's TLS handshake and resists probing well. Turn on Vision. |
| Trojan | TCP | Required | Classic TLS protocol supported by nearly every client. |
| VMess / VLESS + WS | TCP | Optional | Can sit behind a CDN (needs a domain); for direct use the ones above are better. |
| Shadowsocks | TCP / UDP | None | No certificate, the widest client support. The 2022 ciphers are stronger, but old Clash cores cannot use them, so subscriptions leave them out for those clients. |
| SOCKS / HTTP / Mixed | TCP | — | Plain proxies for LAN devices or for chaining other programs; not meant for getting past censorship directly. |
TLS: node certificate, Reality or none
TLS mode decides how the node encrypts and disguises itself; Hysteria2, TUIC and AnyTLS always need TLS.
- Node certificate: uses a certificate on the server and clients verify the domain. Each server's default certificate is used unless you pick one for this line under Certificate.
- Reality: no certificate; it imitates the TLS of the site in Handshake target (masquerade domain). Check tests whether that site works; Suggest tests a list of popular sites and ranks them by latency, one click fills one in. Next to Private key click Generate keypair; next to Short ID click Generate.
- None: plain text, only for CDN origins or internal networks.
- Leave Client fingerprint at the default unless you know you need another.
- A Reality handshake target must support TLS 1.3 and H2 and be reachable from the server; when the line runs on another server, the measured latency is only a hint.
- With a self-signed certificate clients must allow insecure certificates. Subscriptions add this automatically (the setting is Allow insecure certificate in subscriptions).
Transport
Only VLESS, VMess and Trojan have a Transport choice; if unsure keep the default TCP (direct).
- TCP (direct): the fastest.
- ws, httpupgrade: can go through a CDN.
- grpc: pairs well with Reality.
- For VLESS, tick Enable XTLS Vision (TCP + TLS only, recommended).
Hysteria2 port hopping and masquerade
Use port hopping when your ISP throttles single UDP ports; use a masquerade site so probes do not reveal a proxy.
- Port hopping range: such as
20000-30000. The server forwards that whole UDP range to the line's port and clients hop between ports at random. Open the whole UDP range in the security group / firewall; leave it empty to turn hopping off. - Masquerade site: anyone probing the port sees this website instead of a proxy error. Enter a full URL; new lines default to
https://www.bing.com. Empty = no masquerade. - Up Mbps (0 = unlimited) / Down Mbps (0 = unlimited): usually leave at 0.
- Obfs password (salamander; empty = off): usually empty; if you set one, subscriptions pass it to clients automatically.
Which servers run a line
With several servers, a line can run on only some of them.
- Deploy on servers: all ticked (the default) means every server, including servers added later (none ticked counts as all too); tick only some to run the line just there, and subscriptions only list those entries. When you take a server off the line, users, reseller grants and plans that picked that server on this line drop it; those that had picked only removed servers switch to all of the line's servers (named in a dialog after saving), so nobody silently loses the line.
- Dual-stack servers get an extra drop-down in their row, so the line can use IPv4 or IPv6 on that server (the default follows the Servers page).
- A line on several servers has several "entries"; when assigning lines to users, plans or resellers you can tick just the entry on one server.
Rule-based routing
Within one line, send chosen sites out through another exit (streaming through an unlocking server, say) or block them.
- Edit the line and tick Rule-based routing.
- Click + Add rule: choose the Match type (Domain suffix, Full domain, Domain keyword, IP range, Port), enter the values (separate several with commas or new lines) and choose the Egress: direct, an upstream, or Block.
- To add by app: type app names (such as douyin, netflix, openai) in the box next to it and click Look up; rules are added for you and you pick the egress in each.
- Save.
- Rules are checked top to bottom and the first match wins; anything unmatched uses the line's own Upstream.
- An app often uses several domains, so add them together; very short keywords (like ai) catch unrelated sites; traffic to a domain may not match an IP range, so prefer domain rules.
- Untick Rule-based routing and save to remove all rules.
Batch actions, order and cloning
Tick several lines and a batch bar appears at the top.
- Enable, Disable, Set upstream, Deploy on (only with several servers), Clear. A batch change reloads the data plane only once.
- Drag rows to reorder; subscriptions list nodes in the same order.
- More at the end of a row has Clone (a new port is picked), Add a line as upstream (see Lines as upstreams) and delete.
Upstreams and external nodes
Upstreams decide where a line's traffic leaves; external nodes merge nodes from elsewhere into your users' subscriptions.
Add an upstream
An upstream is an exit server: once added, choose it as a line's Upstream and that line's traffic leaves from there.
- Upstreams page → Add upstream.
- Paste the exit node's share link into Import from share link and click Parse, check the fields and save; or pick the type and fill in the fields yourself.
- Click Test to see the latency, then set it as the upstream of a line on the Lines page.
- VLESS, VMess, Trojan, TUIC, Hysteria2, Shadowsocks and SOCKS exits are supported.
- An upstream still used by lines cannot be deleted; change those lines' upstream first.
WARP
Cloudflare WARP gives lines a clean exit, often used for streaming or to let IPv6-only servers reach IPv4 sites.
- On the Ops page, in the Cloudflare WARP card, click Install, then Enable.
- Click Check exit to confirm the exit IP.
- If the Upstream row has no warp yet, click Add as upstream "warp".
- Choose warp as a line's upstream.
- WARP's local port (SOCKS5 port) is 40000 by default and enabling fails if it is taken; after changing the port, enable WARP again.
- One-click install supports Ubuntu / Debian only; on other systems install cloudflare-warp yourself (proxy mode) and have its SOCKS5 proxy listen on the same port. Ops tasks only work on Linux with m-ui running as root.
- If the server's own DNS cannot resolve the package repositories during install (some cloud providers' built-in DNS occasionally fails like this), the task temporarily switches to public DNS (1.1.1.1 / 8.8.8.8, or 2606:4700:4700::1111 / 2001:4860:4860::8888 on IPv6-only servers; on systems without systemd-resolved it writes temporary /etc/hosts entries instead) and restores everything when it ends; the task output says so. If no repository name can be resolved at all, it stops and tells you which domain. If the server's DNS works and only a third-party repository is dead (its domain no longer exists), the task just notes it and installs as usual without touching DNS. When apt is held by automatic system updates, it waits up to 5 minutes and names the process. If you cancel during installation, packages that are being unpacked or configured are finished first, so the package database is not left broken.
- With several servers, the warp upstream points to each server's own
127.0.0.1:PORT: every server that runs a line using warp needs WARP installed and enabled on its own Ops page (same port as on the master); if that is not possible, deploy the line only on servers that have WARP.
Lines as upstreams (chaining)
Forward an entry line's traffic into another of your own lines, for example in through a domestic relay and out through an overseas server.
- On the Upstreams page click Add a line as upstream (or the same item under More at the end of a line's row), then choose the line and Use its entry on server.
- Its settings follow the line automatically, even if the line changes port or protocol; it uses dedicated credentials, takes nothing from users' quotas, and traffic is counted once.
- Loops, deleted lines and deleted entry servers are blocked or flagged. Nodes need v0.7.16 or later.
Upstream groups (automatic failover)
Group several upstreams to always use the fastest one that works and switch automatically when it fails.
- Upstreams page → Add upstream group, pick at least two Members, then choose the group as a line's upstream.
- Members are tested every 30 seconds; the current one is kept unless it is more than 300 ms slower than the fastest, to avoid flapping. On a switch old connections are closed so apps reconnect at once.
- The Upstreams page shows which member each server is using now.
- Nodes need v0.7.16 or later: as soon as an upstream group exists (even before any line uses it), older nodes refuse the whole sync.
Health checks and alerts
Upstreams are tested on a schedule, with optional Telegram alerts on failure and recovery.
- Each server only tests the upstreams its own lines use; upstreams no line uses are marked Unused and are neither tested nor alerted on.
- The status column can show Down, Pending or Stale; the arrow at the end of the row shows each server's results and errors.
- Settings → Upstream health checks: Interval (minutes) (0 = off) and Consecutive failures before alert.
- The Upstream health card on the dashboard has Check now.
External nodes
Merge nodes from elsewhere (an airport subscription, a single share link) into your users' subscriptions, after your own nodes.
- External nodes page → Add external node: choose Subscription (one subscription URL fetched on a schedule) or Share link (a single node).
- Fill in Link / subscription URL; a Name prefix (such as "[Relay] ") helps users tell them apart. Save.
- On the Users page, edit the users who should get them and tick External nodes.
- The master fetches them on a schedule set in Settings → Subscription → External subscription refresh interval (minutes); when a fetch fails, the last good content is kept and the error is shown in the list.
- base64 or plain link lists, Clash YAML and sing-box JSON are supported.
Hide, rename, exclude keywords
Info nodes such as "traffic left" or "website" that airports add, and nodes you do not want to hand out, can be left out.
- Click Show nodes to see every parsed node; tick some and click Hide selected / Show selected; single nodes can be given a new name with Rename.
- Hiding and renaming remember both the name and the node's fingerprint (address, port, password and so on), so they survive renames and reordering by the provider.
- Exclude keywords: nodes whose names contain these words are not output; separate with commas, such as
website,expire,traffic left. It also catches nodes that appear later, which suits info nodes whose names change on every refresh. - When nodes disappear for a while their hide / rename records are kept and apply again when they return; click Clean up once you are sure they are gone.
- With nodes: hiding and renaming need nodes on v0.7.17 or later, excluded keywords v0.7.16 or later; older nodes refuse the whole sync.
Speed tests, mainland checks, use as upstreams
With the nodes shown you can test them right there and turn good ones into upstreams.
- Test all / Test selected: each enabled server really connects once and measures latency, which tells you how the node works as an upstream; tick with hidden to include hidden nodes; Stop test any time. Unsupported means the protocol cannot be turned into an outbound here and cannot be tested.
- Test from China: mainland probes of the three carriers connect to the selected nodes to see whether they are blocked; UDP protocols such as hysteria2 and tuic can only be pinged; domestic relay entries failing from Hong Kong is normal.
- Add as upstreams: tick nodes and give each a name to turn them into upstreams (a duplicate name is an error, nothing is renamed for you).
Certificates
Certificates give lines, the panel and subscriptions TLS / HTTPS. A server can hold several, and issued ones renew automatically.
Add a certificate
Certificate page → Add a certificate, then choose the Certificate source depending on whether you have a domain.
- Domain (auto-issue): first point the domain's A record to the server IP at your DNS provider. Enter the domain and choose the Validation:
- HTTP (temporary listener on port 80): port 80 must be free and reachable from the internet.
- DNS (Cloudflare API): for domains on Cloudflare; enter a Cloudflare API token (with DNS edit permission for the domain; see Creating a Cloudflare API token). Port 80 is not needed and renewal is automatic.
- DNS (add a TXT record by hand): for other DNS providers; add the TXT records shown, and issuing continues once public DNS sees them.
*.example.com) need DNS validation. - No domain (self-signed): click Generate self-signed; leave Addresses in the certificate (auto if empty) empty to use the server's public IP. Every node in subscriptions gets "allow insecure" automatically, so clients need no settings; keep the panel and subscriptions on HTTP.
- Existing certificate: if certbot, aaPanel, nginx or a commercial certificate is already on the server, enter the paths of the Certificate file (fullchain) and the Private key file and click Use this certificate.
http:// to https://, the old links stop working at once and clients must re-import (you are asked once more before adding, when switching the subscription certificate under In use, and when filling in or clearing the certificate paths in the Subscription group of Settings); with Use for panel HTTPS ticked, the panel switches to https:// a few seconds later and the browser follows (a node's panel still needs a restart).Creating a Cloudflare API token
Issuing certificates with DNS (Cloudflare API) needs a Cloudflare API token. Let it manage only the DNS of your domain, so a leak cannot touch anything else.
- Open Cloudflare's token page with the permissions filled in and sign in to your Cloudflare account. The permissions are already set, "Zone → Zone → Read" and "Zone → DNS → Edit", and the token is named m-ui.
- Change "Zone Resources" to "Include → Specific zone → your domain"; do not leave "All zones".
- Click "Continue to summary", then "Create Token".
- Copy the token shown and paste it into Cloudflare API token on m-ui's Certificate page. It is shown only this once: after you leave the page it cannot be viewed again, and a lost token has to be created anew.
- Keep it minimal: the two permissions above, on just the domain you use. Do not use the Global API Key, and do not grant account-level permissions.
- Token leaked? Delete or roll it on the same page and put the new token into m-ui.
- The DNS interface master failover uses to take over subscriptions takes its own token (see What a takeover moves over); create another one the same way.
Where certificates are used
Line inbounds, Panel and Subscription each have their own certificate, changed in the In use card. The Reseller panel shares the panel's certificate by default; to give it its own, enter the Certificate and Private key paths under Settings → Reseller panel (applies on save).
- Click Change next to an item and pick a certificate from the store, or No HTTPS.
- Subscription changes apply immediately (users need the new https link); a new panel certificate needs Restart m-ui; changing the default line certificate restarts the data plane once.
- To give one line its own certificate: edit the line → Certificate; servers without that certificate keep using their own default.
Automatic renewal
Issued certificates renew before they expire and are swapped in without a restart.
- Checked a few minutes after start, then every hour; renewal starts in the last third of the validity period (30 days before expiry for a 90-day certificate).
- Failures are retried after 1, 2 and 4 hours; the first failure is reported at once, then once a day.
- The Auto-renew column of the Certificate store shows each certificate's state: last renewal, number of failures and next retry. Click Renew to renew now, or turn auto-renewal off for one certificate.
- When a certificate needs attention (renewal failing, expiring soon, expired, file unreadable), a "certificates need attention" bar appears at the top; click View to handle it. Node certificates are reported on the master too.
- Certificates issued with DNS (add a TXT record by hand) cannot renew automatically: every renewal needs new TXT records. Re-issue with Cloudflare validation to renew automatically.
- HTTP validation needs port 80 for a moment on every renewal; a TCP line using port 80 makes renewal fail.
- An extra AAAA (IPv6) record that does not point to this server makes validation fail: point it here or delete it.
- Let's Encrypt no longer sends expiry emails: set up Telegram or a webhook at least on the master (see Notifications).
- An Existing certificate is renewed by the tool that issued it (such as certbot); the panel only reads the files and starts reminding you 14 days before expiry. A copy placed in
/etc/m-ui/cert/restored/by a restore on another server is a snapshot from backup time that nothing renews: the store marks it Restored copy, not renewed and reminds you daily from 30 days before expiry; issue a new one or add the certificate again yourself (see Restore).
Certificates on nodes
Every server manages its own certificates on the Certificate page of its own panel.
- Certificates are matched by name across servers: if a line picks a certificate, servers without it use their own default; the line's certificate picker shows which servers have it and how many days are left.
- Nodes usually have no notifications set up, so the master reports their renewal failures and expiries, and the master's Servers page marks cert renewal failing.
- When you issue a real certificate on a node, Use for panel HTTPS is ticked by default; if you keep it, the master must switch to the node's
https://API URL after the node restarts (see Attach a node). Untick it if you do not want that.
Users and plans
A user is one subscription link with a traffic quota, expiry, device limit and speed limit; a plan is a template of those limits.
Create a user
Users page → Add user; fill in the limits, tick the lines and save, and the subscription link is ready.
- Username (subscription id): on the main panel the username is the subscription id by default, so no spaces or / ? # &, and it must be unique. Anyone who knows the username can fetch the subscription, so avoid easy guesses such as test, user1 or real names; safer still, turn off Use the username as the subscription URL under Settings → Subscription so new users get a random token (the username is then just a name), and use Reset subscription link to give existing users random links.
- Username: just a name that does not appear in the subscription link (the link gets a random token automatically). It still cannot contain spaces or / ? # &, and it must be unique across the whole site: a name another reseller or the main panel already uses is refused, so add your own prefix to every name.
- With plans, choose the Plan and click Fill from plan to fill in every limit at once. Otherwise fill in Quota GB (0 = unlimited), Expiry (empty = never), Concurrent devices (0 = unlimited), Upload limit Mbps (0 = unlimited) and Download limit Mbps (0 = unlimited).
- For monthly plans whose traffic resets, tick Periodic traffic reset and set the Reset period (days).
- Tick the Lines. A line on several servers has several entries, and you can give just the entry on one server (switch between server groups; ticks are kept).
- External nodes: ticked external nodes are added after your own nodes in the user's subscription.
- Remark: an order number, contact details and so on. Note: when neither Profile title nor Page title is set, by you or on the main panel, apps show the remark as the subscription name (the username when the remark is empty), so keep anything users should not see out of it.
How quota, expiry and devices are counted
Users who run over or expire are disabled and kicked automatically; renewing or resetting traffic brings them back.
- Traffic: upload + download together; quotas can be decimals (0.1 is about 100 MB). Traffic through a server with a traffic ratio counts with that multiplier.
- Expiry: the user is disabled when it passes. "Expire N days after first connection" overrides the expiry date.
- Periodic reset: every N days used traffic goes back to zero, and users disabled for going over are re-enabled.
- Devices: counted by source IPs online at the same time, across all servers. Several devices behind one Wi-Fi (one public IPv4, or one IPv6 /64) count as one; IPv4 and IPv6 are counted against the limit separately, so one device using both is not counted twice.
- When the limit is reached only new devices are refused; connected ones are not affected. A slot frees up about a minute after another device goes offline.
- Refused connections are highlighted in red in Recent inbound connections on the dashboard, with a Refused badge; hover it for the reason (Refused: device limit). When there were refusals in the last 10 minutes, Needs attention mentions it too.
- Speed limits: on one server, all of the user's connections share the bandwidth; using several servers at once gives one allowance per server. Changes apply immediately.
Subscription links, QR codes and sharing
Click a user's name (or Details) to open the details; the subscription links and QR code are at the top.
- Under Subscription there are two links: the one with
?format=clashis for Clash only; the one without?format=is the universal link, and that is the one to send (a browser opens the landing page, and apps get the right format when they fetch it). Click Copy next to it. - The QR code in the details is the Clash link, meant for scanning with a Clash-type app; a phone camera would only download a config file, so let such users open their landing page and scan or import from there.
- The More menu in the list can also copy the Clash subscription, the Link subscription (the universal link) or the sing-box subscription.
- Opened in a browser, the link shows the user's landing page: usage, expiry, one-tap import for each app and a QR code (see Subscriptions and landing page).
- Shared: users can create a temporary link for a friend on their landing page; traffic and devices count against them. The details show that link, and Revoke cancels it at once.
- Link leaked? More → Reset subscription link. The link gets a new random token, all protocol credentials are regenerated, the old link stops working and online devices are disconnected; send the new link to the user.
- The details also show Online devices (IP) (and which line each IP uses), a traffic chart and the user's lines.
Renew, extend and change plans
In the More menu (or the user's details), Renew… and Change plan… handle renewals, upgrades and downgrades.
- Renew…: Choose a plan (the user's current plan by default), then the mode: Renew (reset traffic, extend), Extend (keep traffic) or Only assign to this plan (keep quota and expiry). Periods renews several periods at once (1–120): enter 3 or 12 to sell a monthly plan quarterly or yearly. For a single user the new expiry and quota are previewed below as you type. Renewing or extending with a plan is an explicit sale, so users disabled as manual are enabled too (the dialog warns first; Only assign to this plan (keep quota and expiry) leaves enabled / disabled alone).
- Extend 30 days: one click adds 30 days for users who have an expiry date (for "N days after first connection" users whose clock has not started, it is added to N); users disabled for expiry come back, users disabled by hand stay disabled.
- Change plan…: choose the New plan and one of three ways under How:
- Replace now: the new plan starts now for N periods; time and traffic left on the old subscription are dropped.
- Stack: keeps the time left (and one-off traffic) and adds N periods; for plans with periodic resets traffic is a per-period allowance and does not stack. An expired subscription carries nothing over; if the new plan has no time or traffic limit, the existing finite expiry or quota is kept.
- Prorate: converts the value left on the old subscription into time on the new plan (one-off traffic plans also get traffic), using both plans' Reference price (optional); the new plan starts now. The user must have a plan and change to a different one, both plans need a price, and periods can be 0.
- This period's usage: Auto (reset for replace and prorate, kept for stack), Keep (carry on) or Reset (new period).
- The dialog previews Before and After live and marks it as an upgrade or a downgrade. Effects that hurt the user, such as an earlier expiry or going over quota at once, are shown in red, and you must tick I have read the effects marked in red, proceed anyway before Change plan works.
- With a single user, the Renew… and Change plan… dialogs get their own duplicate-protection id each time they open, so a double click or a network retry only runs once. Batch Apply plan on several selected users has no such protection: if it stops with an error partway, the users already renewed stay renewed; before retrying, check their expiry in the list (or Plan history in the details) and leave out those already done.
- Plan history in the details lists recent renewals and plan changes.
Plans
A plan is a template of limits that new accounts, renewals and batch actions can apply directly.
- Plans page → Add plan: a Name (such as 100G/month), Description, Quota (GB), Duration (days), devices and speed limits.
- Tick Periodic traffic reset for monthly resets, and Start the clock at first connection for gift cards.
- Lines: applying the plan replaces the user's lines with these; empty = keep the user's lines.
- Rate-limit rules: ticked rules apply to every user of the plan, current and future.
- Reference price (optional): only used by "prorate" when changing plans and never shown to users; give two plans the same price to swap them at equal value.
- The Plans page shows how many users each plan has.
- Editing a plan does not change users who already applied it; renew or change their plan to move them to the new limits.
- Resellers only see and use the plans they created themselves.
Batch actions
Tick several users and a batch bar appears at the top (the header checkbox ticks the current page only).
- Enable, Disable, Extend, Apply plan, Reset traffic, Delete.
- Bulk create: creates Count users at once from a Username prefix; for Naming choose prefix + 8 random chars or prefix + sequence (001…, random subscription URL). Afterwards every new user's link is listed and can be copied in one go. These are Clash links (ending in
?format=clash); for users who do not use Clash, remove the?format=clashat the end to get the universal link. - Export CSV: exports the user list; its subscription column holds Clash links too.
Why a user is disabled, and kicking
The status column says why a user is disabled, which tells you how they come back.
- over quota, expired: renewing, resetting traffic or extending the expiry re-enables them automatically.
- manual: resetting traffic, extending the expiry or a periodic reset never brings them back. Renewing or extending with a plan (Renew…, batch Apply plan) and Change plan… are explicit sales and do enable them: the renew, batch apply-plan and change-plan dialogs warn first that users disabled by hand will be enabled, and in a batch they name them so you can untick anyone who should stay off. Renewals and plan changes through the external API enable them as well.
- Limited: temporarily slowed down by a rule (see Rules).
- Kick: closes the user's connections on every server (hysteria2, TUIC and AnyTLS sessions are closed entirely). If the user is still enabled the app reconnects right away, so disable them first to cut them off.
- Filter the list with All, Online, Enabled, Disabled, Expired or Over quota, or show one plan only. After selecting the whole page (on a phone, after ticking any user), the batch bar can select every match at once; this replaces the earlier selection with exactly the current matches. Users ticked before you changed the filter or search stay selected, and a batch action asks first when some of them are not in the current list.
Import users from an old panel
Use this when your lines are already set up in m-ui and you only want to bring the old users over.
- On the Users page click Import from old panel, upload the old panel's .db file and click Import.
- Users with the same name are overwritten with the old database's usage, quota, expiry, status and periodic reset, plus a non-empty remark and description; the rest are created with the old panel's credentials. You can tick Give newly created users every existing line.
- Importing only users keeps m-ui's own lines, inbound ports, subscription port and path: users must import their new m-ui subscription link, so send it to everyone before you turn the old panel off.
- To move lines, upstreams and settings too, see Moving from an old panel.
Rules (temporary speed limits)
Rules slow users down for a while: for example everyone at 30 Mbps in the evening peak, or 20 minutes of limits for anyone who used 1 GB within 10 minutes.
Two kinds of rules
- Schedule: limits during a time window on chosen days of the week and lifts them outside it. Times use the panel time zone, and an end before the start means the window crosses midnight; no Weekdays ticked means every day.
- Burst: when upload + download within the last Window (minutes) reaches Trigger (GB, up + down), the user is limited for Limit for (minutes); it lifts by itself and triggers again if reached again.
Create a rule
- Rules page → Add rule: give it a name, choose the Type and fill in the condition.
- Set Upload Mbps / Download Mbps; 0 leaves that direction unchanged.
- Cap at the user's own limit: when on (the default) the result is never faster than the user's own limit; turn it off to apply the rule's values directly, for example to loosen limits at certain hours.
- Targets can be combined: all users (including future ones), users of a plan, all users of a reseller, or users ticked one by one.
- Save.
Which limits are active
- When several rules hit the same user, the strictest wins.
- In the Active column, view shows who is limited right now and for how long; the user list also marks them Limited.
- Changes apply to live connections immediately; the master evaluates rules every 10 seconds and syncs them to nodes. Disabling a rule lifts its limits at once.
- Rule limits are not shown on users' landing pages. To hear about burst limits: Settings → Notifications → Notify when a burst limit triggers.
Reseller panel
Resellers sell accounts for you: you give them lines and quotas, they create users in their own reseller panel, and they only ever see their own users and the plans they made.
The reseller panel only covers the users under your account: the site owner gives you lines and quotas, and you create accounts, renew them and watch usage here.
Create a reseller
- Resellers page → Add reseller: the Name is the reseller's login name.
- Tick the Allowed lines: resellers can only give these lines to their users, and you can allow just the entry on one server.
- Set the limits: Traffic quota GB, Max users, Device pool, Bandwidth pool · up Mbps / Bandwidth pool · down Mbps, Expires (empty = never); 0 = unlimited.
- Send them the reseller panel address: it is shown below the reseller list and in the message after creating one (default port 2054, path
/dl/).
- New resellers have no password: within 24 hours they sign in with their name and an empty password, then set one. If that window passed or they forgot the password: More → Reset password (this also clears their 2FA and API token and opens a new 24-hour window).
- Unticking a line removes it from all of that reseller's users at once.
- Reset traffic sets the used traffic of all their users back to zero.
- Resellers' users do not appear on the main panel's Users page; open the reseller's Details to see them.
- The reseller panel's port, path and certificate are under Settings → Reseller panel; untick Enable the reseller panel if you do not need it, and remember to open 2054/tcp in the firewall.
How reseller limits work
- Traffic quota: counts all usage of all their users; resetting traffic, renewing or deleting users on the reseller panel does not reduce it. Only "reset traffic" on the main panel sets it back to zero.
- Device pool: the most devices all their users may have online at once (across all servers). When it is full only new devices are refused; connected ones are not affected.
- Bandwidth pool: the combined speed of all their users, one pool per server.
- Any single user can be given any value, but the totals are capped by these pools.
- If the reseller expires, is disabled or runs over the traffic quota, all their users are disabled at once and their subscriptions stop working.
First sign-in and password
- Open the reseller panel address you were given (default
http(s)://SERVER:2054/dl/). - Enter your reseller name as the username; the first time, leave the password empty and click Sign in.
- When asked, Set a password (at least 8 characters), and sign in with it from then on.
What the reseller panel can do
- Dashboard: quota used, account expiry, number of users, online users and devices; Needs attention warns when the quota, expiry or device pool is close to the limit, and Expiring soon and Running out of data list the users who need a renewal.
- Users: add, edit, renew, extend, reset traffic, kick, reset subscription links, batch actions, usage charts and online devices. New users only need a name; their subscription link is a random token.
- Plans: only the plans you created yourself are visible and usable.
- Account: quota, password, two-factor authentication, your own subscription page texts and the external API.
- You can only assign the lines the site owner allowed (possibly just on some servers).
Account page
The reseller panel's Account page holds your sign-in security, your quota, and the subscription page your users see.
- My quota: traffic used, the device pool (online / limit, and the total handed out to users), bandwidth, expiry and number of users. When the device pool is full it also says how many new devices were refused recently.
- Password: change your password.
- Two-factor authentication (2FA): see Account and two-factor authentication.
- Subscription page: the texts your users see: Profile title (the subscription name shown in apps), Page title, Footer contact, Purchase / renew link and Notice (multi-line); empty fields use the main panel's. You can also turn off the page or temporary sharing for your users.
- Landing page logo: upload your own logo, which applies at once; without one, the main panel's is used.
- External API: for your own shop or bot (see External API).
Subscriptions and landing page
Clients import the subscription link; the same link opened in a browser is the user's own landing page.
Subscription links and formats
- They look like
http(s)://DOMAIN-OR-IP:2056/sub/USERNAME(or a random token). - One link is enough: the format follows the client that fetches it. Clash-type apps (Clash Verge, mihomo, Stash) get a Clash config, sing-box apps (SFA, SFI and so on) get a sing-box config, and NekoBox, v2rayN, Shadowrocket and others get plain links.
- To force a format, append
?format=clash(Clash),?format=json(sing-box) or?format=mihomo(Clash for the new core). - Each line appears once per server, with the server name as a suffix; servers whose traffic ratio is not 1 get a tag such as
x2. - Node addresses are server IPs by default (the domain is only the SNI), so a poisoned DNS on the client cannot break them.
- Disabled, expired or used-up users get a 404 when their client fetches the subscription, and the lines stop letting them in.
How users import it
- Easiest: send the universal link (the one without
?format=) and have the user open it in a phone or computer browser, then tap one-tap import for their app or scan the QR code. - The download arrow at the top right of the one-tap import button opens a download page with apps for each system (iOS, Android, Windows, macOS, Linux). Its address contains the user's own subscription link (so does its "← Back to subscription" link), so do not forward it; to help someone install an app, send them the app's website or release page.
- Users can also copy the link and paste it into their app's "add subscription".
- The name shown in apps is the first non-empty one of your Profile title, Page title, the main panel's Profile title and Page title, the user's Remark and the username. If your customers should not see the site owner's name, set a Profile title of your own. Shadowrocket and Clash Verge fix the name when the subscription is added, so after changing the title users must remove and re-add it, or use one-tap import on the landing page (which carries the title).
Subscription settings
Under Settings → Subscription and Subscription formats and templates.
- Profile title, Update interval (hours).
- Use the username as the subscription URL: on by default; when off, new users get random tokens and existing users keep their links.
- Allow insecure certificate in subscriptions: automatic by default (on with a self-signed certificate).
- Node address in subscriptions: IP (recommended) or domain.
- Base64-encode link subscription, Show traffic notice node on top, External subscription refresh interval (minutes).
- Pick the format by client: on by default; when off, links without
?format=always get plain links. - Custom templates: Clash template (YAML, empty = built-in) / sing-box template (JSON, empty = built-in). Start with Fill in the built-in Clash template and edit it; nodes and groups are filled in by the panel, and mistakes are reported when you save.
Landing page
What users see when they open their subscription link in a browser: usage, expiry, one-tap import, QR codes, plus your notice and contact details.
- Edit it under Settings → Subscription page; resellers edit theirs under Account → Subscription page (empty fields follow the main panel).
- Edit it under Account → Subscription page; empty fields use the main panel's.
- Show a page when the subscription URL is opened in a browser: when off, browsers just get the subscription content.
- Page title, Footer contact, Notice (multi-line).
- Purchase / renew link: adds a purchase / renew button to the landing page (the main button when the user has expired, run out or been disabled).
- Show “Powered by m-ui” at the bottom of landing pages: resellers' landing pages never show it.
- Landing page logo: click Upload / replace; it applies at once, no save needed. PNG, JPEG, GIF, WebP and SVG are accepted; the browser scales the image to fit 480×160 and converts it to PNG (64 KB at most). It is shown 28 pixels high and at most 160 wide on the landing page, and used as the browser tab icon. Landing pages follow the visitor's dark mode and put a light backdrop behind the logo there, and the preview in the settings shows both; a white logo on a transparent background is hard to see in either. Restore default brings back the built-in logo. Resellers without a logo use the main panel's, and nodes follow the master.
- Users who ran out, expired or were disabled can still open their landing page, which shows the reason and whom to contact; their clients get a 404. Links that match no user show an "invalid subscription link" page in browsers.
Links in the notice and contact details
Notice (multi-line) and Footer contact can contain clickable links; only the text is shown on the page.
| Write | Shown on the page |
|---|---|
Support(https://t.me/support) | "Support", clickable |
[Clash/Mihomo guide](https://example.com/a) | "Clash/Mihomo guide", clickable |
Website https://example.com | the address itself becomes a link |
Tg: @username | @username, opens Telegram |
WhatsApp: +34 600 000 000 | the number, opens WhatsApp |
- If the text contains
/or a colon, or the link contains brackets, use the[text](link)form. Half-width and full-width brackets both work, including【text】(link)as typed with a Chinese input method. - In
text(link)a space before the bracket is fine; the link text runs back from the bracket to the nearest punctuation or the previous link. - Telegram keywords are Tg, Telegram, 电报 and 飞机, followed by
@usernameor+number; WhatsApp keywords are WhatsApp, WA and WS, followed by+number; an English or Chinese colon both work. - Only http(s), tg, mailto and tel links are accepted; anything else is shown as plain text.
- The notice can be up to 4000 characters and the contact details up to 300; the current count is shown below each box.
Backup and migration
One zip file is the whole panel: the database (lines, users, traffic, settings) plus certificates, including certificate files outside the data directory (such as certbot's) that the settings or the certificate store point to. Keep it safe and you can move or reinstall without losing any data.
Back up
- Backup page → Backup now: Download it, or Save on server (listed under Backups on server).
- Scheduled backup: Hour of day (-1 = off) (in the panel time zone, see Settings → Panel → Time zone) and Copies to keep; tick Also push to Telegram once Telegram notifications are set up.
- Command line:
m-ui backup -db /etc/m-ui/m-ui.db -out backup.zip, or option 9 in them-uimenu.
Restore
- Backup page → Restore: choose the backup file (zip or .db) and click Restore.
- After you confirm, m-ui restarts by itself and replaces the database and certificates. Certificate files outside the data directory that the settings or the certificate store point to (an Existing certificate, or certificate paths imported from an old panel) are never written back to their original paths: if the certificate at the original path on this server is usable (valid now, covers every domain of the one in the backup, matches its key, and is not older than the backup's or has more than two weeks left), it stays in use; otherwise the copy from the backup goes into
/etc/m-ui/cert/restored/and the settings and the store are pointed there. The result is shown once at the top of the page. Should a panel, subscription or reseller-panel certificate file still be missing, that service starts with a temporary self-signed certificate (still HTTPS) and raises an alert instead of failing to start. - The previous database is kept as a
.bak-*file, but only the latest two are kept: after several restores in a row the oldest one is deleted. If you are unsure which backup to use, first click Backup now and download the current database.
- A new server can install and restore in one step (the command is under Moving to another server).
- With the service stopped you can also restore from the command line:
m-ui restore -db /etc/m-ui/m-ui.db -from backup.zip.
- What goes into
/etc/m-ui/cert/restored/is a copy taken at backup time: if certbot, aaPanel or a similar tool used to renew it, nothing renews it any more, and the certificate store marks it Restored copy, not renewed. Right after restoring, issue a new one on the Certificate page, or install certbot on this server, add its files as an Existing certificate and switch over; do not wait for the 30-day expiry reminder. - Restoring the master's backup on another server and starting it makes that server the master: it takes over every node with a higher epoch, and the old master turns into a node if it starts again later (even if master failover was never turned on; see Backups, restores and moving servers). If you only want to look inside a backup, do not restore and start it on a machine that is online.
- While a temporary self-signed certificate stands in, apps get a certificate error when updating subscriptions, and browsers warn on the panel and the reseller panel: put the certificate back or switch to another one, as the certificate alert at the top of the page says.
Moving to another server
The Migration wizard on the Backup page moves the whole panel to a new server from a backup in four steps. When subscriptions use a domain, ports, credentials and subscription links stay the same: point the domain at the new server and users follow.
systemctl disable --now m-ui on it (see Backups, restores and moving servers).- Copy the backup zip to the new server and run
bash <(curl -fsSL https://raw.githubusercontent.com/Maoyangui/m-ui/main/deploy/install.sh) --restore /root/m-ui-20261111-030000.zip(use your own file path; the same command works on amd64 and arm64, installs the latest version, then restores, certificates included). The wizard shows this command too. - Open the panel with the new server's IP (same port and path as before) and check that the lines are running; nodes are reconnected automatically.
- Point your domain to the new IP at your DNS provider, and use Check DNS in the wizard to see whether the major resolvers have picked it up.
- When users are fine on the new server, run
systemctl disable --now m-uion the old one (stops it and keeps it from starting at boot), or uninstall with option 14 of them-uimenu.systemctl stopalone is not enough: both servers hold the same data, node tokens and Telegram bot, so when the old VPS reboots (provider maintenance, say) it starts again and keeps serving, pushing to nodes and notifying with stale data.
- If the subscription link holds an IP (no domain for subscriptions), it changes to the new server's IP, and so do the master's node addresses; step 3 does not help then. Best give subscriptions a domain and send users the new link once before moving. If you can only send everyone the new link after moving, the old server has to keep running until most have switched; follow the next two items meanwhile.
- If you have nodes and the old server stays up for a while, use Rotate token under Settings → Pairing on every node before restoring, and once the new server is restored enter the new tokens in those rows on the new master's Servers page (Edit → Pairing token); holding the old token, the old master can no longer push to them. Otherwise, whenever something changes on the old master by itself while both run (users disabled on expiry or over quota, a periodic reset), it pushes its stale configuration to the nodes, and users created or renewed on the new master can no longer connect through them.
- If the old server stays up for a while, untick Enable Telegram notifications under Settings → Notifications on it: both servers use the same bot and keep cutting each other off, so bot commands may land on the old server and change stale data, and notifications arrive twice.
- Open the same ports on the new server's security group and firewall as on the old one: panel, subscriptions, reseller panel and every line (UDP for Hysteria2, TUIC and port-hopping ranges).
- WARP is installed into the system and is not in the backup: if lines use the warp upstream, install and enable WARP on the new server's Ops page first (same port as before).
- If an Existing certificate was renewed by certbot, aaPanel or a similar tool, the new server does not have that tool, and what gets restored is a copy that nothing renews (see Restore): after moving, issue a new one on the new server's Certificate page, or install certbot there and add it again.
- If nodes allow their panel port only from the old master's IP, add the new master's IP first, or the new master cannot reach them.
- Apart from turning off Telegram notifications, change nothing on the old panel while both run, and keep that time as short as possible.
Moving from an old panel
- Everything (lines, upstreams, users, settings): add a parameter when installing on the new server,
bash <(curl -fsSL https://raw.githubusercontent.com/Maoyangui/m-ui/main/deploy/install.sh) --import /path/to/old-panel.db. Inbound ports, user credentials, the panel path and the subscription path are kept; match the items below yourself so that clients need no changes:- Certificates: the panel and subscriptions both keep using the old panel's panel-certificate paths, but the files do not come with the database. If the old panel used HTTPS, copy the certificate and key to the same paths on the new server before installing; nothing renews the copied files there, so once the domain points at the new server, issue a new certificate on the Certificate page and switch to it.
- If the old panel had a separate certificate for subscriptions (usual when the subscription domain differs from the panel's), subscriptions now use the panel certificate and apps report a certificate mismatch when updating: copy that certificate over too, then after installing go to the Certificate page → Add a certificate → Existing certificate and tick only Use for subscription HTTPS under Apply to. If the old panel served subscriptions over http while the panel used https, subscriptions are now https as well: in In use, click Change next to Subscription and choose No HTTPS.
- The subscription port becomes 2056: if the old panel served subscriptions on another port, change it back with option 6 of the
m-uimenu after installing. - A separate subscription domain is not carried over: add it with
m-ui set -db /etc/m-ui/m-ui.db subDomain=DOMAIN. - If subscription links use a domain, point it at the new server; if they use the old server's IP, the links change after the move and users need the new ones.
- Users only: Users page → Import from old panel (see Import users from an old panel).
Notifications (Telegram)
Get alerts on Telegram (or a webhook): users expiring, upstreams failing, certificate renewals failing, servers getting blocked… and manage users from your phone with the bot.
Set up Telegram notifications
- In Telegram, create a bot with @BotFather and copy its token (like
123456:ABC-DEF…). - Message @userinfobot to get your chat ID (group and channel IDs are negative). Then send your own bot a message, otherwise it cannot write to you.
- Settings → Notifications: tick Enable Telegram notifications, fill in Bot token and Chat ID, click Save.
- Click Send test message; if it arrives on your phone, you are done.
socks5://127.0.0.1:40000.What gets notified
Tick each event in the Notifications group; Telegram and the webhook share these switches.
- Panel login / repeated failures
- User auto-disabled (expired / quota), User expiring soon (how early: Days before expiry), User quota warning (at Warn at usage percent)
- Notify when a burst limit triggers
- Upstream down / recovered, Data plane stopped / recovered
- Mainland reach problem / recovered
- Certificate issued / renewal / expiry (node certificates are reported by the master too)
- Daily report, sent at Daily report hour (0-23, panel time zone)
- Master failover: a standby noticing the master is lost, waiting for your confirmation code, a finished takeover, a master switch that finished or failed, and the old master coming back as a node are reported too (see Set as master and master failover); these alerts are not affected by the Data plane stopped / recovered switch.
Telegram bot
With Telegram bot ticked you can send commands to the bot from your phone to manage users.
| Command | What it does |
|---|---|
/status | Overview |
/find keyword | Find users |
/user name | User details and subscription link |
/extend name days | Extend the expiry |
/reset name | Reset traffic |
/enable name, /disable name | Enable / disable (disabling also disconnects) |
/kick name | Disconnect |
/backup | Send a backup |
/help | List all commands |
Webhook
To feed alerts into your own system (a chat relay, a ticket system…), use a webhook.
- Webhook URL: ticked events are also POSTed here as JSON with
event,textandtime. Empty = not sent. - Webhook secret: when set, requests carry an
X-M-UI-Signatureheader (sha256=HMAC of the body) so the receiver can verify them.
Ops, logs and updates
Tune the server, read logs, troubleshoot connections and update, all without a terminal.
System tuning
System tuning on the Ops page: swap, the open-file limit, time sync, kernel parameters and BBR; the defaults suit most VPSes.
- Tune everything applies them all, or adjust one item and click Run; progress appears live in Task output.
- The same page can cap the system log (journald) size and retention. It holds the logs of every service on the machine; limiting it does not affect the panel.
- When disk space is short, swap is made smaller (2G kept free for the system, at most a quarter of the disk), and below 512MB it is skipped: a big swap file on a small disk fills it up.
- WARP is on this page too (see WARP). Ops tasks only work on Linux with m-ui running as root.
Disk nearly full: alerts and clean-up
Every server reports how full the disk holding m-ui's data directory is. 90% used or less than 1GB left counts as nearly full, 97% or less than 300MB as full: writing the database, logs or certificates can fail at any moment.
- A nearly full node shows 💾 and its used percentage in its status on the Servers page (hover for how much the system logs, the package cache and swap take), counts as an item in Needs attention on the dashboard, and Telegram gets one message (another when it becomes full, and "recovered" once it is below 87% with at least 1.5GB free). The master's own disk is watched the same way and points you to the Ops page.
- Clean-up: on the master's Servers page open More on that row and click Clean up disk, no need to log in to the node; for this server use Run on Clean up disk on the Ops page. It clears the package cache, vacuums journald to its limit, keeps only the last 5MB of text logs over 100MB, deletes rotated logs older than a day and installs an hourly timer (m-ui-syslog-cap.timer) that rotates syslog as soon as it passes 200MB. m-ui's data and backups are untouched and lines keep running.
- On Google Cloud servers with the Ops Agent installed, the dialog has one more checkbox: when its reports fail it floods syslog with whole stack traces, a common reason small disks fill up; ticking it disables and masks the agent (the Google Cloud console then shows no monitoring metrics for that server).
- Older nodes cannot be cleaned remotely: upgrade them first, or clean up from the Ops page of their own panel.
- To undo the timer:
systemctl disable --now m-ui-syslog-cap.timer; to bring the Ops Agent back:systemctl unmaskits three services, thensystemctl enable --now google-cloud-ops-agent.
Logs
The Logs page has three kinds: Subscription access, Core log and Audit.
- Subscription access: who fetched a subscription, from which IP and with which app.
- Core log: the data plane's and panel's runtime log. The copy in the panel lives in memory only (about 10,000 lines at most, cleared on restart); the same lines also go to the system log (see
journalctl -u m-ui), and Clear only empties the panel's copy. Cap the system log's size and retention on the Ops page. Logging can be switched off to save resources. - Data-plane level: warn by default, warnings and errors only. Switch to info or debug while troubleshooting (it applies at once) and back to warn afterwards; info writes tens of thousands of lines an hour and slows the disk down.
- Audit: who did what and when (panel, external API and Telegram bot actions).
- Subscription access and audit logs can Auto-clean (keep 1 day, 1 week, 1 month or forever); every kind can be emptied with Clear.
Recent inbound connections
Recent inbound connections on the dashboard helps when a user says they cannot connect: did their IP reach the server, and on which line?
- It lists connections that passed the protocol handshake and authentication, with user, line, server, count and last time.
- Connections refused by a device limit or a reseller's device pool are listed too, highlighted in red with a Refused badge; hover it to see whether it was Refused: device limit or Refused: reseller device pool full.
- The latest 10 are shown; "Show all" expands the list inside the card (and lets you filter by IP, user or line). The filter above switches between connections, refused ones and handshake failures.
- Sources whose packets arrived but failed the handshake or authentication (wrong certificate, SNI, REALITY public key / short_id, password / UUID) are under the "Handshake failed" filter, split into TLS handshake failed and Auth failed, with the reason; hysteria2 and tuic only record auth failures. Older nodes do not report these, and the card names them.
- An IP missing from the list usually means the packets never reached the server (security group, firewall, client network). To check whether they arrive on a TCP line, set Data-plane level to info for a while and look for
inbound connection from. Hysteria2, TUIC and other UDP lines only log that line after the handshake and authentication succeed (nothing anywhere for a wrong certificate or SNI; a wrong password only shows under "Handshake failed"), so its absence proves nothing there; capture packets on the server instead, such astcpdump -ni any udp port PORT.
Updating
When a new version is out, an arrow appears next to the version number at the bottom left; click it to update in one step.
- Arrow → Update now: the download is verified, the program replaced and restarted, and the panel reloads after a dozen seconds. Users, lines, subscription links and certificates stay as they are; connections on this machine drop for a moment.
- If the new version fails to start, the old one is put back automatically and a bar at the top explains it; Got it dismisses it.
- Nodes are full installations and update from their own panels; keep master and nodes on the same version.
- You can also run
m-uiover SSH and choose option 10. Like the arrow in the panel, it retries through the local WARP when GitHub cannot be reached directly, so IPv6-only servers (which cannot reach GitHub) update fine once WARP is installed. Running the one-line installer again also updates, but the script does not use WARP by itself: on an IPv6-only server first runexport ALL_PROXY=socks5h://127.0.0.1:40000(use your WARP port), or upload the package by hand.
Command line and SSH menu
If the panel will not open or you forgot the password, run m-ui on the server for a numbered menu.
- Menu: 1 show panel address / account, 2 restart, 3 stop, 4 start, 5 reset the admin password, 6 change panel port / path / subscription port, 7 reset all settings, 8 recent logs, 9 back up now, 10 update to the latest version, 11 generate a self-signed certificate, 12 switch between master and node, 13 turn off two-factor authentication, 14 uninstall.
m-ui info: prints the panel address, path and account status.m-ui passwd: resets the admin password (and turns off two-factor authentication).m-ui set -db /etc/m-ui/m-ui.db key=value: changes a setting directly, such aswebPort=3053.m-ui render: prints and validates the current sing-box configuration.- Option 15 and
m-ui ha status/takeover/set-master/pause/resume/reset: Set as master and master failover (see Command line). Upgrading or restarting from the menu pauses takeovers first. - Data lives in
/etc/m-ui/:m-ui.db(database),cert/(certificates),backups/(scheduled backups).
Settings at a glance
The Settings page saves group by group, each with its own Save. Port, listen address and certificate changes take effect on save: the panel switches its listener in place and the browser follows to the new address, and the subscription service and reseller panel do the same, so Restart m-ui at the top is rarely needed (a node's panel port and certificate are the exception, see the Q&A below).
Role and panel
- Role: Run as node (secondary server) (see Attach a node).
- Panel: Domain (the domain used by subscriptions and nodes, also the TLS SNI), Time zone (all times in the panel use it), Listen address, Port, Path, Certificate / Private key (normally filled in from the Certificate page), Trusted reverse proxies (see Panel address and ports), Supporters list and online panel count.
- A new panel path applies as soon as you save and the browser follows it; port, listen address and certificate changes need a restart.
- With port 443 (HTTPS) or 80 (HTTP), addresses need no port number; the panel and subscriptions cannot share a port.
Subscriptions, subscription page, reseller panel
- Subscription, Subscription formats and templates: see Subscription settings.
- Subscription page: landing page texts, the purchase link and the sharing switch; see Landing page.
- Reseller panel: Enable the reseller panel, listen address, port (default 2054), path (default
/dl/) and certificate (empty = same as the panel).
Notifications, health checks, data plane
- Notifications: see Notifications (Telegram).
- Upstream health checks: Interval (minutes) (0 = off), Consecutive failures before alert.
- Mainland reachability: Automatic checks, Interval (minutes), Globalping token (optional).
- Data plane: Data-plane certificate, Upstream test URL, Stats bucket (seconds), Keep traffic history (days), Let users reach private / local addresses (off by default), Block BitTorrent. Changing the last two restarts the data plane once and syncs to nodes.
- About: version number and what the panel and subscription addresses look like.
External API
For shops, billing systems and bots: with one token they can create users, renew, change plans, enable or disable users and fetch subscription links, without signing in to the panel.
Turning it on
- Admin page → External API: turn on the switch at the top right of the card (hovering it shows Enable / disable the external API), then copy the Base URL and the Token.
- Account page → External API: turn on the switch at the top right of the card (hovering it shows Enable external API), then copy the Base URL and the Token.
- Send the token with every request: the header
Authorization: Bearer TOKEN(orX-API-Key: TOKEN), with JSON request bodies. - Once it is on, Endpoints (what each call does) and an Example (curl) with your base URL and token filled in appear below the token, ready to copy; while it is off the endpoint list is folded away but can still be read.
- The token carries all of your panel permissions: keep it in server-side code only, never in a web page or an app. If it leaks, click Regenerate and the old token stops working at once.
- Call the API on the master only; write calls on a node are refused.
- A reseller token only reaches your own users, your own plans and the lines you were allowed; it stops working as soon as you are disabled, expire or have your password reset.
Multiple keys, permissions and the source IP allowlist
- The token above is the default key: it can do everything and keeps working after the upgrade. While the external API is on, the card also has Extra keys: click New key, give it a name (say "Shop" or "Telegram bot") and tick only the permissions it needs.
- Seven permissions: View users, Create users, Change users (edit fields, enable / disable, reset usage, kick, reset the subscription link), Delete users, Renew & change plans, View plans and Panel info (overview, servers, lines, online users). Calling something a key is not allowed to do returns 403 naming the missing permission.
- Each key has its own Edit, Regenerate (the old token stops working at once) and Delete buttons; the list shows when and from which IP it was last used. With the master switch off, no key works.
- Source IP allowlist: off by default. When on, only the listed IPs or ranges can call the API (default and extra keys alike), one per line; the page shows your current source IP and Add it puts it on the list. The main panel and every reseller have their own list.
- Behind a reverse proxy (Nginx, Caddy …), first fill in Trusted reverse proxies under Settings → Panel, otherwise every request seems to come from the proxy itself.
- Extra keys only work on the master; with master failover on, they keep working after a standby takes over.
Common calls
Paths go after the base URL; {name} can be the username or the user id.
| Call | What it does |
|---|---|
GET /ping | Connectivity and version |
GET /plans | List plans |
GET /users | List users (?q= to search) |
POST /users | Create a user; pass plan to apply a plan at once |
GET /users/{name} | User details (subscription links, online IPs) |
PATCH /users/{name} | Change fields: expiry, quota, devices, lines… |
POST /users/{name}/enable · /disable | Enable / disable |
POST /users/{name}/reset · /kick | Reset this period's usage / kick |
POST /users/{name}/rotate | Reset the subscription link and credentials |
POST /users/{name}/plan | Renew (renew) or extend (extend); periods renews N periods at once, and a request without any plan field renews the current plan. /renew is an alias |
POST /users/{name}/change | Change plan: replace, stack or prorate |
GET /users/{name}/plan-ops | Plan history, newest first |
GET /users/{name}/sub | Subscription links |
DELETE /users/{name} | Delete the user |
Preview, no duplicates, confirm downgrades
Renewals and plan changes touch users' money and time, so the API has three safety nets.
- Preview:
"dryRun": trueonly calculates and returns before / after, which a shop can use for quotes. - No duplicates (idempotency): send a
requestId(or theIdempotency-Keyheader, such as your order number) and retries with the same id run only once, so time is never added twice. - Downgrade confirmation: if a plan change would put the user over quota at once or bring the expiry forward, the API answers 409 with the full preview; call again with
"force": trueto go ahead. - Calls marked idempotent and dry run in the panel's endpoint list support these.
- Renewals and plan changes are explicit sales: users disabled by hand are enabled as well, so do not renew someone you want to keep disabled.
Security
A changed default password, two-factor authentication and a hidden panel address stop most trouble.
Account and two-factor authentication
- Change the password or username: Login account on the Admin page.
- Change the password: Password on the Account page.
- Two-factor authentication (2FA): click Generate secret, scan the QR code with an authenticator app (Google Authenticator, Microsoft Authenticator, Authy, 1Password…), enter the 6-digit code it shows and click Verify & enable. From then on signing in needs the password plus a code.
- Lost your phone? SSH in and run
m-ui: option 13 turns two-factor authentication off; resetting the password with option 5 turns it off too. - Lost your phone or password? Ask the site owner to reset your password on the main panel (two-factor authentication is cleared with it).
Panel address and ports
- Change the default port and path: Settings → Panel → Port / Path.
IP:port/alone always returns 404, so a port scan does not reveal the panel. - Serve the panel over HTTPS: when adding a certificate, tick Use for panel HTTPS; it takes over a few seconds later and the browser moves to the https address (a node needs a restart).
- Open only the ports you need in the firewall, and allow nodes' panel ports only from the master's IP (add the new master's IP after changing masters). This keeps out outsiders, not users who come in through the proxy; see the next section.
- Login protection: 10 wrong attempts from one source within 10 minutes block it for 5 minutes, and 5 wrong attempts in a row can send a Telegram alert (Panel login / repeated failures). 10 wrong external API tokens likewise pause that source for 5 minutes (counted separately from logins).
- If the panel, reseller panel or external API sits behind a reverse proxy (Nginx, Caddy, ...), enter the proxy addresses under Settings → Panel → Trusted reverse proxies (
127.0.0.1, ::1for a proxy on the same server). Otherwise every request comes from the proxy itself, and ten bad attempts from anyone lock everyone (admins, resellers, shops, bots) out for 5 minutes. Once set, only requests from a listed address have their source taken fromX-Forwarded-For(the rightmost address not in the list) orX-Real-IP; the proxy must append or overwrite that header (Nginx:proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;, Caddy does it by default). Leave it empty without a proxy.
Data-plane safety switches
- Let users reach private / local addresses: off by default, so users cannot reach services that listen only on 127.0.0.1 (such as the WARP port), your internal network or the cloud metadata address (169.254.169.254) through the proxy. Public addresses of your servers are not blocked: opening the panel, calling the external API from a shop or bot whose traffic goes through the proxy, refreshing subscriptions while connected and signing in to the reseller panel all work. This also means that if you restrict panel access by source IP, a user going through a server of the cluster arrives with that server's IP; the panel and the external API rely on passwords, two-factor codes and tokens. Turn it on only if users really need internal services.
- The panel port is not covered: users can still open
SERVER-PUBLIC-IP:PANEL-PORTthrough the proxy; on the many VPSes whose public IP sits on the network card, that traffic goes through the server's loopback, so firewall IP allow-lists do not stop it. Do not rely on allow-lists alone to protect a panel: change the default port and path, use a strong password and turn on two-factor authentication. - Block BitTorrent: refuses BitTorrent through the proxy so your VPS does not attract copyright complaints.
- Give nodes HTTPS API URLs; otherwise tokens and user credentials are synced in plain text.
- Backup zips contain user credentials and private keys, and the external API token equals admin rights: keep all of them safe.
Which outside services the panel contacts
m-ui has no telemetry and collects no usage data. Apart from your own servers, the panel only contacts outside services in these cases; the table also says how to turn each one off.
| Service | When and why | How to turn it off |
|---|---|---|
| GitHub | Update check: about 20 seconds after start, then every 6 hours; the subscription service also checks the client version for the landing page's download page every 6 hours. Updates are downloaded from here too. | Cannot be turned off; if GitHub is unreachable the panel works the same, just without update notices |
Cloudflare (cdn-cgi/trace), ipify | Detecting the server's public IPv4 / IPv6 (used for node addresses in subscriptions by default): at start, then every hour | Cannot be turned off |
| Globalping | Mainland reachability: the server's IP and port are sent to its public probe network, when you click a check and for Automatic checks (on by default, every 90 minutes) | Settings → Mainland reachability → untick Automatic checks |
| Let's Encrypt | Issuing and renewing Domain (auto-issue) certificates; normally only the local expiry date is checked, and it connects only when a renewal is due. With DNS validation (Cloudflare or manual TXT records) the panel also asks the public DNS of Cloudflare and Google (1.1.1.1, 8.8.8.8) whether the TXT records are visible yet | Do not use auto-issue, or turn off auto-renewal for that certificate in the store |
| Cloudflare API | Adding and removing TXT records when issuing or renewing with DNS (Cloudflare API) | Not contacted unless you use that validation |
| Telegram | Sending notifications and running the Telegram bot | Not contacted unless enabled under Settings → Notifications |
| GitHub, jsDelivr, ntfy.sh, TronGrid | Supporters list: reading the list when the Feedback / Support page is opened (at most hourly), adding a name and checking for the payment; online panel count: one download of an empty file from GitHub a day | Settings → Panel → untick Supporters list and online panel count |
| Globalping, the Cloudflare / Alibaba Cloud / Tencent Cloud DNSPod APIs | Master failover: overseas probes try the master when deciding whether it is lost; with subscriptions taken over too, the DNS interface points the subscription domain to the new master after a change and reissues its certificate when needed | Turn off Overseas probe witness; with Master duties only (the default) the DNS interface is never contacted |
Google (www.gstatic.com) | Upstream checks and tests: it is the default Upstream test URL. When lines on this server use upstreams (WARP, an exit server and so on), it is fetched through each upstream every 10 minutes; for lines that use an upstream group, the core also fetches it through every member every 30 seconds; clicking Test on an upstream and external node speed tests fetch it too | Change the Upstream test URL to another address; setting Interval (minutes) to 0 only stops the scheduled checks, upstream groups keep testing |
| Addresses you enter | Webhook, external subscriptions, the Telegram proxy | Leave them empty |
| Only when you click | Updating, installing WARP (Cloudflare's package repository; when the server's DNS cannot resolve the repositories it also asks 1.1.1.1 and 8.8.8.8) and Check exit, Look up in rule-based routing (the v2fly domain lists on GitHub), Reality Check and Suggest (connect to candidate sites), external node speed tests, Pre-check DNS / port on the Certificate page and Check DNS in the migration wizard (ask the public DNS of Cloudflare, Google and Alibaba, and detect the public IP once) | Not contacted unless you click |
FAQ and troubleshooting
Start from the symptom; if it is not here, search for a keyword at the top.
Cannot connect
- The subscription refreshes, but nodes do not connect?
- Have the user refresh the subscription once, then check in this order: is the line's port open in the security group / firewall (Hysteria2 and TUIC need UDP); is the user disabled (see the status column); is the device limit full. Recent inbound connections on the dashboard shows whether their IP reached the server.
- Device limit reached / some devices cannot connect?
- The devices online at the same time (by source IP, across all servers) hit the limit, so new devices are refused. Wait about a minute after another device goes offline, or raise the limit. A phone switching between Wi-Fi and mobile data changes IP and may count twice for a short while.
- IPv6 nodes do not work?
- Usually the cloud security group lacks
::/0rules (add TCP and UDP separately) or ip6tables / ufw blocks it; also make sure the user's own network has IPv6. Outbound-only IPv6 such as WARP or NAT cannot take incoming connections. The IPv6 inbound check on the Servers page tells you directly whether it is reachable (see Connect address, IPv4 and IPv6). - Everyone in one region suddenly cannot connect?
- On the Servers page click Check mainland reach: IP blocked means change the IP, Port blocked means change the port.
Panel and servers
- Opening
IP:2053/shows 404? - On purpose: the root does not redirect, so the panel path is not given away to scanners. Open the full address, such as
http://IP:2053/app/. Forgot the path? SSH in, runm-uiand choose option 1. - Forgot the password / lost the 2FA phone?
- SSH in and run
m-ui: option 5 resets the admin password (and turns off 2FA), option 13 only turns off 2FA. - Changed the port, listen address or certificate and the page didn't move?
- The main panel switches its listener in place a second or two after you save, and the browser follows once the new address answers. If it never does, the firewall (security group) probably doesn't allow the new port, the certificate isn't trusted, or the domain doesn't point here yet; the page shows the new address so you can open it directly. A node's panel port and certificate don't switch on their own (the master reaches the node through that address): update the API URL on the master's Servers page first, then click Restart m-ui at the top of the node's Settings page, or use menu option 2. A new path applies on save.
- A node shows offline?
- Read the reason on the Servers page and see offline nodes. Nodes with self-signed certificates need Skip certificate verification; after re-issuing a node's certificate use More → Reset fingerprint.
- Certificate renewal fails?
- Check the reason in the Auto-renew column of the certificate store: HTTP validation needs port 80 free; manual-DNS certificates cannot renew automatically; an AAAA record pointing elsewhere also breaks validation. See Automatic renewal.
- WARP will not enable?
- Read the task output on the Ops page. Common causes: port 40000 is taken, so set another SOCKS5 port and enable again; or the system is not Ubuntu / Debian, which one-click install does not support, so install WARP yourself (see WARP).
- Subscriptions return 429?
- One IP fetched a subscription more than 120 times in a minute and was rate-limited, usually an app refreshing too often. The limit is also the main protection against someone guessing usernames to collect subscriptions, so do not turn it off; if you really need more, raise it (to 600, say):
m-ui set -db /etc/m-ui/m-ui.db subRateLimit=600, and consider turning off Use the username as the subscription URL so new users get random tokens.
Subscriptions and users
- The subscription name in the app is wrong?
- Set Profile title under Settings → Subscription (resellers set theirs on their Account page; when a reseller leaves both the Profile title and the Page title empty, their users get yours too); without it the page title, the user's remark and the username are used, in that order.Set Profile title under Account → Subscription page; without it your page title, then the main panel's Profile title and Page title, the user's remark and the username are used, in that order. If your customers should not see the site owner's name, set a Profile title of your own. Shadowrocket and Clash Verge fix the name when the subscription is added, so users must remove and re-add it, or use one-tap import on the landing page.
- What do users see after running out or expiring?
- Their landing page still opens in a browser, with the reason, contact details and a renew button (if a purchase link is set) at the top; their apps get a 404. Renewing or resetting traffic brings them back at once.
- A subscription link leaked?
- The user's More → Reset subscription link: the old link and credentials stop working at once; send the new link.
- A reseller cannot sign in?
- New resellers sign in the first time with an empty password. If the 24-hour window passed or the password is forgotten, the site owner uses Resellers → More → Reset password on the main panel.
Known limitations
These are current design limits, not faults; they may improve later.
- VLESS / VMess multiplexing (Mux) and XUDP: when a client turns on Mux, or carries UDP over XUDP, one outer connection is authenticated once and the streams opened inside it never look at the user table again; the server accepts this unconditionally and no line setting can block it. Disabling or deleting a user, resetting a subscription link or kicking a user only closes the streams running inside; the outer connection stays up, and the client can open new streams in it until it reconnects. To cut it off at once, disable and re-enable the line (a full reload) or restart m-ui. Hysteria2, TUIC and AnyTLS are not affected: disabling and kicking close the whole session.
- Device limits across servers have a window of about 5 seconds: the master collects every server's online IPs and hands them out every 5 seconds, so a user who connects through several servers within those seconds can go over the limit in total. Devices that are already connected are not kicked when that happens (a full device pool only refuses new devices); the count drops back once the extra devices have been idle for about a minute.
- A full reload does not send Hysteria2 a close notice: changes such as adding or deleting a line, or changing its port or protocol, reload the whole data plane; connected Hysteria2 clients get no connection-close notice and only notice after an idle timeout of about 30 seconds, then reconnect, so it looks stuck for a while. Changes to users, speed limits and upstreams are applied hot and are not affected.
- The mainland reachability check covers IPv4 only: most mainland home-broadband probes have no IPv6, so testing IPv6 from them would report healthy servers as blocked; only IPv4 is checked, and IPv6 inbound gets a separate check from probes outside the mainland (it only shows whether the port answers and does not judge blocking). See Mainland reachability.
Feedback, support and supporters
Feedback / Support at the top right of the panel: reach the author, report problems and support the project.
Reporting problems
- The page links to the author's Telegram, the docs, bug reports and discussions. Include the version number when reporting (one click copies it on that page).
- Mask tokens, UUIDs and subscription links in logs before sharing them.
Supporters list
- Under "Support the project", enter your name and amount and click Add my name, then send exactly the amount shown in USDT (TRC20); if it arrives within 60 minutes it is credited to that name.
- The list is matched with payments by a scheduled job on GitHub, which GitHub often delays by hours, so a name usually appears in the Supporters list of every panel a few hours after the payment arrives; if it is still missing after a day, message the author on Telegram.
- m-ui has no telemetry and collects no usage data. The supporters list and the online panel count (each panel downloads an empty file from GitHub once a day, and the download count says how many are running) are the only connections that serve none of the panel's features, and neither carries any identifier.
- To stop these two: Settings → Panel → untick Supporters list and online panel count. That switch covers only these two; for its features the panel also contacts GitHub (update checks), Globalping (mainland reachability), Let's Encrypt, Telegram and others, listed with how to turn each off under Which outside services the panel contacts.