feat(amneziawg): add opt-in Linux kernel datapath (#6877)

* feat(amneziawg): add opt-in Linux kernel datapath

Add the kernel backend as an explicit per-inbound option while keeping the embedded backend as the default. Include host preflight, UI/API support, the bundled installer CLI, lifecycle and accounting integration, regression tests, and upstream-facing documentation. Kernel mode is NAT-only and rejects unsupported routing, IPv6, forwarding, and pinned-listen configurations. Local saves check the local host; remote nodes check their own host during apply.

Preserve adopted interface accounting across panel restarts, retain manager state after failed teardown so the job can retry, prevent embedded startup while a kernel interface remains live, and prune collector state for removed peers. Tested the restart accounting path on Debian 13 with XanMod 7.1.11 on x86_64; Docker and cross-kernel coverage are not claimed.

* fix(amneziawg): align readiness and endpoint reporting

Expire endpoint sightings using the latest handshake and sweep stale addresses for the polled interface. Keep the readiness API schema, generated client types, and ready-host empty blocker list consistent; watch the nested form field and defer local readiness checks for remote targets. Document safe rollback before using a build without kernel support.

Regression evidence: the idle endpoint test failed before the collector change because the old address remained visible after 31 minutes; endpoint tests pass after the fix. The form component suite passes 3 tests; restoring the invalid array watch made its off-mode severity test fail, while the corrected dot-path watch passes. Targeted Go regressions across amneziawgkern, job, and service pass.

* style(amneziawg): format readiness test

* test: reproduce kernel AWG client validation gaps

* test(service): cover kernel AWG shared client fanout

* fix(amneziawg): validate kernel client fanout and config values

* test(amneziawgkern): cover owned interface lifecycle recovery

* fix(amneziawgkern): recover owned interfaces on restart

* test(amneziawgkern): retain visibility after recovered cleanup failure

* fix(amneziawgkern): report recovered interfaces while cleanup retries

* style(amneziawgkern): satisfy static analysis

* test(amneziawgkern): cover long rendered peer comments

* fix(amneziawgkern): accept long generated config comments

* test(amneziawgkern): refuse foreign occupied interfaces

Capture the current Ensure ordering failure with real temporary config paths and manager side-effect boundaries.

* test(amneziawgkern): cover stale interface collisions

Extend the Ensure regression across absent links, mismatched live interfaces, cached manager state, and Remove teardown.

* fix(amneziawgkern): verify interface ownership before mutation

Refuse to replace or tear down links unless the canonical config is a valid panel-owned file and its key matches the live interface. Preserve normal adoption and key rotation, and document migration of legacy unmarked configs.

Validation: go test ./internal/amneziawgkern -count=1; go test -race ./internal/amneziawgkern -count=1; golangci-lint run ./internal/amneziawgkern/...; git diff --check.

* build: update Go toolchain to 1.27.3

* test(amneziawg): reproduce unsafe key rotation recovery

Keep the previous owned config authoritative until teardown succeeds, and require fresh managers to rebuild structural key changes. These regressions expose the stuck live-key/disk-key mismatch after teardown failure.

* fix(amneziawg): recover interrupted key rotations

Keep the old owned config on disk until a structural rebuild has confirmed the previous interface is down. Fresh managers only adopt when the live config and desired structural identity match, so retries and removals retain the key needed to prove ownership.

* fix(scanner): align Go image with module version

* fix(docs): pin pnpm release with bootstrap fix

pnpm 12.9.1 restores a Node launcher before its postinstall replaces the target with ELF; pnpm 11 then runs that binary as JavaScript. Pin 12.10.0, which includes the shim fix, so the docs CI bootstrap can switch versions safely.

* fix(xray): build core from pinned module

The configured Xray release asset tag is unpublished, and the latest published binary lacks GetUsersStats used by the panel. Build the packaged core from the exact Xray module version already selected in go.mod for Docker and release targets.

* fix(tests): stabilize local network fixtures

Keep the TUIC stream fragmentation check on a working UDP loopback path,
allocate the AmneziaWG fixture ports dynamically, and wait for a real
Xray stats response before starting API mutation assertions. Recreate
failed readiness channels so an early connection cannot stall the probe.

Verified host and offline parallel Go suites, repeated occupied-port and
UDP tests, race/shuffle runs, and golangci-lint. Production behavior and
dependency versions are unchanged.

* fix(i18n): add the kernel-mode AmneziaWG keys to sk-SK

main gained the sk-SK locale after this branch added its kernel-mode keys
to the other 13, so i18n-dead-keys.test.ts failed on the merged tree.

* refactor(amneziawgkern): apply kernel interfaces with direct commands, no awg-quick

awg-quick evaluates PostUp/PostDown through a root shell, so every value the
panel rendered into its config was one validation slip away from root command
execution. The interface is now built with direct ip/awg/nft execs from a
setconf-only file: link add, awg setconf, address, mtu, an atomically replaced
nftables table per inbound, and the IPv4 forwarding sysctl written directly.

- Panel-owned names and paths: xui-awg<id> interfaces, xui_awg<id> NAT tables
  and configs under the panel's data dir, so nothing collides with an
  operator's own awg0/awg1 awg-quick tunnels in /etc/amnezia/amneziawg.
- FORWARD accepts (comment 3x-ui:xui-awg<id>) when iptables is present: Docker
  and ufw set the FORWARD policy to DROP, which silently black-holed the tunnel.
- A full panel stop records the final counters and tears the interfaces down,
  like the embedded datapath; a stopped panel enforces no quota or expiry.
  Crash survivors are still adopted without a rebuild.
- The job reads counters before reconciling, and from every managed interface,
  so a client disabled for quota, or a removed inbound, is charged for its last
  interval instead of losing it with the dropped peer.
- An unchanged reconcile tick forks no process (it probed the live key with
  `awg show` every 10s); readiness no longer loads the module from a GET.

Verified on the real module (WSL2 6.6 kernel, v3.1.20260906): create, peer and
egress changes in place, SIGKILL adoption with the same ifindex, SIGTERM
teardown leaving no link, table, FORWARD rule or config behind.

* fix(amneziawg): gate kernel host readiness only when a save starts the datapath

Every save of a kernel-mode inbound re-ran the host preflight, so a host that
lost its module (a kernel upgrade without a DKMS rebuild) refused even
disabling the inbound or switching it back to embedded mode. Host blockers now
apply only when the save starts the kernel datapath: a new inbound, a switch
from embedded, or enabling a disabled one. Feature blockers (IPv6, forwarded
ports, pinned listen) still apply to every save.

* feat(nodes): refuse kernel-mode AmneziaWG pushes to nodes that predate it

A node built before kernel mode drops the unknown kernelMode field and serves
the inbound on the embedded datapath while the master's form shows kernel
mode on. Nodes now advertise awg-kernel in X-3x-Node-Caps, and Remote refuses
to push a kernel-mode inbound to a node that has not advertised it, learning
the caps with an inbound list first when this Remote has not heard from it.

* fix(amneziawg): pin the kernel module installer to verified commits

The installer ran as root and built whatever upstream tag sorted newest at
install time. It now clones fixed tags (module v3.1.20260906, tools
v3.1.20260812) and refuses unless each resolves to its recorded commit. The
udp_tunnel perl patch is gone: those releases carry the kernel 7.1.5 compat
upstream, so the patch never matched.

* fix(i18n): translate the kernel-mode AmneziaWG strings

All thirteen non-English locales carried the English text verbatim.

* fix(amneziawg): skip the kernel traffic flush when no kernel interface runs

Shutdown listed the desired AmneziaWG inbounds from the database even on a
panel with no kernel interface, an unneeded query on every stop. A server
stopped before its database was opened panicked on it, which turned
TestServerStopWhenXrayNotRunningSucceeds red whenever it ran first.

---------

Co-authored-by: MHSanaei <ho3ein.sanaei@gmail.com>

frontend/src/api/queries/useAmneziawgKernelReadiness.ts

@@ -0,0 +1,25 @@
+import { useQuery } from '@tanstack/react-query';
+import { ReadinessSchema, type Readiness } from '@/generated/zod';
+import { HttpUtil } from '@/utils';
+import { keys } from '@/api/queryKeys';
+
+export type KernelReadiness = Readiness;
+
+async function fetchKernelReadiness(): Promise<KernelReadiness> {
+  const msg = await HttpUtil.get('/panel/api/inbounds/amneziawgKernelReadiness', undefined, {
+    silent: true,
+  });
+  if (!msg?.success) throw new Error(msg?.msg || 'Failed to fetch kernel readiness');
+  return ReadinessSchema.parse(msg.obj);
+}
+
+// Probing the module is cheap but not free, and the answer only changes when an
+// admin installs something, so a short stale window is plenty.
+export function useAmneziawgKernelReadiness(enabled: boolean) {
+  return useQuery({
+    queryKey: keys.inbounds.amneziawgKernelReadiness(),
+    queryFn: fetchKernelReadiness,
+    enabled,
+    staleTime: 30_000,
+  });
+}

frontend/src/api/queryKeys.ts

@@ -29,6 +29,7 @@ export const keys = {
     root: () => ['inbounds'] as const,
     slim: () => ['inbounds', 'slim'] as const,
     options: () => ['inbounds', 'options'] as const,
+    amneziawgKernelReadiness: () => ['inbounds', 'amneziawgKernelReadiness'] as const,
   },
   clients: {
     root: () => ['clients'] as const,

frontend/src/generated/examples.ts

@@ -410,6 +410,10 @@ export const EXAMPLES: Record<string, unknown> = {
     "scope": "admin",
     "token": "new-token-string"
   },
+  "Blocker": {
+    "code": "tools",
+    "detail": "awg"
+  },
   "Client": {
     "adTag": "0123456789abcdef0123456789abcdef",
     "allowedIPs": [
@@ -1069,6 +1073,16 @@ export const EXAMPLES: Record<string, unknown> = {
     "xrayState": "",
     "xrayVersion": "25.10.31"
   },
+  "Readiness": {
+    "blockers": [
+      {
+        "code": "tools",
+        "detail": "awg"
+      }
+    ],
+    "installCommand": "sudo /usr/local/x-ui/x-ui install-awg-kernel",
+    "ready": false
+  },
   "RealityScanResult": {
     "alpn": "h2",
     "certChainBytes": 3427,
@@ -1115,6 +1129,7 @@ export const EXAMPLES: Record<string, unknown> = {
     "jmax": 0,
     "jmin": 0,
     "keepaliveTimeout": "",
+    "kernelMode": false,
     "maxHandshakeAttempts": "",
     "mtu": 0,
     "primaryDns": "",

frontend/src/generated/schemas.ts

@@ -1677,6 +1677,23 @@ export const SCHEMAS: Record<string, unknown> = {
     ],
     "type": "object"
   },
+  "Blocker": {
+    "description": "Blocker is one unmet requirement.",
+    "properties": {
+      "code": {
+        "example": "tools",
+        "type": "string"
+      },
+      "detail": {
+        "example": "awg",
+        "type": "string"
+      }
+    },
+    "required": [
+      "code"
+    ],
+    "type": "object"
+  },
   "Client": {
     "description": "Client represents a client configuration for Xray inbounds with traffic limits and settings.",
     "properties": {
@@ -4305,6 +4322,37 @@ export const SCHEMAS: Record<string, unknown> = {
     ],
     "type": "object"
   },
+  "Readiness": {
+    "description": "Readiness is the host's ability to run any kernel-mode inbound at all.",
+    "properties": {
+      "blockers": {
+        "example": [
+          {
+            "code": "tools",
+            "detail": "awg"
+          }
+        ],
+        "items": {
+          "$ref": "#/components/schemas/Blocker"
+        },
+        "type": "array"
+      },
+      "installCommand": {
+        "example": "sudo /usr/local/x-ui/x-ui install-awg-kernel",
+        "type": "string"
+      },
+      "ready": {
+        "example": false,
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "blockers",
+      "installCommand",
+      "ready"
+    ],
+    "type": "object"
+  },
   "RealityScanResult": {
     "properties": {
       "alpn": {
@@ -4487,6 +4535,10 @@ export const SCHEMAS: Record<string, unknown> = {
       "keepaliveTimeout": {
         "type": "string"
       },
+      "kernelMode": {
+        "description": "KernelMode runs this inbound on the AmneziaWG kernel module (internal/amneziawgkern)\ninstead of the embedded amneziawg-go + gVisor stack.",
+        "type": "boolean"
+      },
       "maxHandshakeAttempts": {
         "type": "string"
       },

frontend/src/generated/types.ts

@@ -1,4 +1,5 @@
 // Code generated by tools/openapigen. DO NOT EDIT.
+export type BlockerCode = string;
 export type GeoKind = string;
 export type OnlineAPISupport = number;
 export type ProcessState = string;
@@ -408,6 +409,11 @@ export interface ApiTokenView {
   token?: string;
 }
 
+export interface Blocker {
+  code: BlockerCode;
+  detail?: string;
+}
+
 export interface Client {
   adTag?: string;
   allowedIPs?: string[];
@@ -973,6 +979,12 @@ export interface ProbeResultUI {
   xrayVersion: string;
 }
 
+export interface Readiness {
+  blockers: Blocker[];
+  installCommand: string;
+  ready: boolean;
+}
+
 export interface RealityScanResult {
   alpn: string;
   certChainBytes: number;
@@ -1018,6 +1030,7 @@ export interface ServerSettings {
   jmax: number;
   jmin: number;
   keepaliveTimeout?: string;
+  kernelMode?: boolean;
   maxHandshakeAttempts?: string;
   mtu?: number;
   primaryDns: string;

frontend/src/generated/zod.ts

@@ -1,5 +1,8 @@
 // Code generated by tools/openapigen. DO NOT EDIT.
 import { z } from 'zod';
+export const BlockerCodeSchema = z.string();
+export type BlockerCode = z.infer<typeof BlockerCodeSchema>;
+
 export const GeoKindSchema = z.string();
 export type GeoKind = z.infer<typeof GeoKindSchema>;
 
@@ -429,6 +432,12 @@ export const ApiTokenViewSchema = z.object({
 });
 export type ApiTokenView = z.infer<typeof ApiTokenViewSchema>;
 
+export const BlockerSchema = z.object({
+  code: z.lazy(() => BlockerCodeSchema),
+  detail: z.string().optional(),
+});
+export type Blocker = z.infer<typeof BlockerSchema>;
+
 export const ClientSchema = z.object({
   adTag: z.string().optional(),
   allowedIPs: z.array(z.string()).optional(),
@@ -1033,6 +1042,13 @@ export const ProbeResultUISchema = z.object({
 });
 export type ProbeResultUI = z.infer<typeof ProbeResultUISchema>;
 
+export const ReadinessSchema = z.object({
+  blockers: z.array(z.lazy(() => BlockerSchema)),
+  installCommand: z.string(),
+  ready: z.boolean(),
+});
+export type Readiness = z.infer<typeof ReadinessSchema>;
+
 export const RealityScanResultSchema = z.object({
   alpn: z.string(),
   certChainBytes: z.number().int(),
@@ -1079,6 +1095,7 @@ export const ServerSettingsSchema = z.object({
   jmax: z.number().int(),
   jmin: z.number().int(),
   keepaliveTimeout: z.string().optional(),
+  kernelMode: z.boolean().optional(),
   maxHandshakeAttempts: z.string().optional(),
   mtu: z.number().int().optional(),
   primaryDns: z.string(),

frontend/src/lib/xray/inbound-defaults.ts

@@ -333,6 +333,7 @@ export function createDefaultAmneziawgInboundSettings(): AmneziawgInboundSetting
       primaryDns: '8.8.8.8',
       secondaryDns: '8.8.4.4',
       externalInterface: '',
+      kernelMode: false,
       ipv6Enabled: false,
       ipv6Subnet: '',
       ipv6ExternalInterface: '',

frontend/src/pages/api-docs/endpoints.ts

@@ -283,6 +283,13 @@ export const sections: readonly Section[] = [
         responseSchema: 'InboundOption',
         responseSchemaArray: true,
       },
+      {
+        method: 'GET',
+        path: '/panel/api/inbounds/amneziawgKernelReadiness',
+        responseSchema: 'Readiness',
+        summary:
+          'Whether this host can run an AmneziaWG inbound on the kernel module. Returns ready, host blocker codes (root/tools/module/nft), and the command that fixes them. Saving an inbound also checks its features and rejects IPv6, port forwarding, routeThroughXray, or a pinned listen address that the kernel backend cannot honor.',
+      },
       {
         method: 'GET',
         path: '/panel/api/inbounds/allLinks',

frontend/src/pages/inbounds/form/protocols/amneziawg.tsx

@@ -1,9 +1,11 @@
 import { useId } from 'react';
 import { useTranslation } from 'react-i18next';
-import { Button, Form, Input, InputNumber, Space, Switch } from 'antd';
+import { useFormContext, useWatch } from 'react-hook-form';
+import { Alert, Button, Form, Input, InputNumber, Space, Switch, Typography } from 'antd';
 import { ReloadOutlined } from '@ant-design/icons';
 
 import { FormField } from '@/components/form/rhf';
+import { useAmneziawgKernelReadiness } from '@/api/queries/useAmneziawgKernelReadiness';
 
 interface AmneziawgFieldsProps {
   awgPubKey: string;
@@ -18,6 +20,18 @@ export default function AmneziawgFields({
 }: AmneziawgFieldsProps) {
   const { t } = useTranslation();
   const uid = useId();
+  const kernelModeOn = useWatch({ name: 'settings.server.kernelMode' });
+  const nodeId = useWatch({ name: 'nodeId' }) as number | null | undefined;
+  const remoteTarget = typeof nodeId === 'number';
+  const { formState } = useFormContext();
+  const { data: readiness } = useAmneziawgKernelReadiness(!remoteTarget);
+  const hostReady = remoteTarget || readiness?.ready !== false;
+  // The master can probe only its local host; a remote node checks on apply.
+  const savedKernelMode = Boolean(
+    (formState.defaultValues as { settings?: { server?: { kernelMode?: boolean } } } | undefined)
+      ?.settings?.server?.kernelMode,
+  );
+  const toggleDisabled = !hostReady && !savedKernelMode;
   return (
     <>
       <Form.Item htmlFor={`${uid}-privateKey`} label={t('pages.xray.amneziawg.privateKey')}>
@@ -213,6 +227,44 @@ export default function AmneziawgFields({
       >
         <Switch />
       </FormField>
+      <FormField
+        name={['settings', 'server', 'kernelMode']}
+        label={t('pages.xray.amneziawg.kernelMode')}
+        extra={t('pages.xray.amneziawg.kernelModeHint')}
+        valueProp="checked"
+      >
+        <Switch disabled={toggleDisabled} />
+      </FormField>
+      {!hostReady && (
+        <Alert
+          type={kernelModeOn ? 'warning' : 'info'}
+          showIcon
+          message={t('pages.xray.amneziawg.kernelUnavailable')}
+          description={
+            <>
+              <ul style={{ margin: '0 0 8px', paddingInlineStart: 20 }}>
+                {(readiness?.blockers ?? []).map((b) => (
+                  <li key={`${b.code}:${b.detail ?? ''}`}>
+                    {t(`pages.xray.amneziawg.kernelBlocker.${b.code}`, {
+                      defaultValue: b.code,
+                    })}
+                    {b.detail ? ` (${b.detail})` : ''}
+                  </li>
+                ))}
+              </ul>
+              {readiness?.installCommand ? (
+                <Typography.Paragraph
+                  copyable={{ text: readiness.installCommand }}
+                  code
+                  style={{ marginBottom: 0 }}
+                >
+                  {readiness.installCommand}
+                </Typography.Paragraph>
+              ) : null}
+            </>
+          }
+        />
+      )}
     </>
   );
 }

frontend/src/schemas/protocols/inbound/amneziawg.ts

@@ -67,6 +67,9 @@ export const AmneziawgServerSchema = z.object({
   // z.object's default unknown-key stripping doesn't silently drop it from
   // an existing stored settings blob on the next save.
   routeThroughXray: z.boolean().default(false).optional(),
+  // kernelMode runs this inbound on the DKMS kernel module instead of the
+  // embedded userspace stack -- no Xray routing, sniffing, IPv6 or port forwarding.
+  kernelMode: z.boolean().default(false).optional(),
   // Upper bounds match amneziawg-go's own UAPI parsers (device/uapi.go):
   // jc/jmin/jmax are uint32, s1-s4 uint16. Wider values make IpcSet fail.
   jc: clearedToDefault(z.number().int().min(0).max(4294967295).default(5)),

frontend/src/test/amneziawg-kernel-readiness.test.tsx

@@ -0,0 +1,79 @@
+import { Form } from 'antd';
+import { FormProvider, useForm } from 'react-hook-form';
+import { describe, expect, it, vi } from 'vitest';
+import { waitFor } from '@testing-library/react';
+
+import AmneziawgFields from '@/pages/inbounds/form/protocols/amneziawg';
+import { HttpUtil, Msg } from '@/utils';
+import { makeTestQueryClient, renderWithProviders } from './test-utils';
+
+interface FormValues {
+  nodeId: number | null;
+  settings: { server: { kernelMode: boolean } };
+}
+
+function Harness({ nodeId, kernelMode }: { nodeId: number | null; kernelMode: boolean }) {
+  const form = useForm<FormValues>({
+    defaultValues: { nodeId, settings: { server: { kernelMode } } },
+  });
+  return (
+    <FormProvider {...form}>
+      <Form>
+        <AmneziawgFields
+          awgPubKey="public-key"
+          regenInboundAwg={() => {}}
+          regenInboundAwgObfuscation={() => {}}
+        />
+      </Form>
+    </FormProvider>
+  );
+}
+
+const unavailable = new Msg(true, '', {
+  ready: false,
+  blockers: [{ code: 'tools', detail: 'awg' }],
+  installCommand: 'sudo x-ui install-awg-kernel',
+});
+
+describe('AmneziaWG kernel readiness in the inbound form', () => {
+  it('shows an informational warning while kernel mode is off', async () => {
+    vi.spyOn(HttpUtil, 'get').mockResolvedValue(unavailable);
+
+    const { container, getByRole } = renderWithProviders(
+      <Harness nodeId={null} kernelMode={false} />,
+      { queryClient: makeTestQueryClient() },
+    );
+
+    await waitFor(() => expect(getByRole('alert')).toBeTruthy());
+    expect(container.querySelector('.ant-alert-info')).toBeTruthy();
+    expect(container.querySelector('.ant-alert-warning')).toBeNull();
+  });
+
+  it('shows a warning when an enabled local kernel inbound is unavailable', async () => {
+    vi.spyOn(HttpUtil, 'get').mockResolvedValue(unavailable);
+
+    const { container, getByRole } = renderWithProviders(<Harness nodeId={null} kernelMode />, {
+      queryClient: makeTestQueryClient(),
+    });
+
+    await waitFor(() => expect(getByRole('alert')).toBeTruthy());
+    expect(container.querySelector('.ant-alert-warning')).toBeTruthy();
+  });
+
+  it('does not use master readiness to block a remote-node inbound', async () => {
+    const get = vi.spyOn(HttpUtil, 'get').mockResolvedValue(unavailable);
+
+    const { container, getByText } = renderWithProviders(<Harness nodeId={7} kernelMode />, {
+      queryClient: makeTestQueryClient(),
+    });
+
+    await waitFor(() => expect(container.querySelector('.ant-alert')).toBeNull());
+    const kernelModeItem = getByText('Kernel mode').closest('.ant-form-item');
+    expect(kernelModeItem?.querySelector('[role="switch"]')?.getAttribute('disabled')).toBeNull();
+    expect(get).not.toHaveBeenCalledWith(
+      '/panel/api/inbounds/amneziawgKernelReadiness',
+      undefined,
+      expect.anything(),
+    );
+  });
+});