opnsense_if_assign

Instructions

Implementation Reference

• src/tools/interfaces.ts:206-218 (handler)

  The handler function for the opnsense_if_assign tool. Parses args with IfAssignSchema, constructs CLI args (--slot, --if, --descr), and runs the remote PHP helper script 'if_assign.php' via SSH. Returns the helper's JSON response, exit code, and stderr.

  case "opnsense_if_assign": {
    const ssh = requireSshClient();
    const parsed = IfAssignSchema.parse(args);
    const cliArgs = [`--slot=${parsed.slot}`, `--if=${parsed.if}`];
    if (parsed.descr !== undefined) {
      cliArgs.push(`--descr=${parsed.descr}`);
    }
    const { response, exitCode, stderr } = await ssh.runHelper(
      "if_assign.php",
      cliArgs,
    );
    return renderHelperResult(response, exitCode, stderr);
  }

• src/tools/interfaces.ts:17-23 (schema)

  Zod schema for input validation of opnsense_if_assign. Validates slot (optN format), if (device name like vlanNN or igb0), and optional descr (up to 120 chars).

  const IfAssignSchema = z.object({
    slot: z.string().regex(SlotRegex, "slot must match /^opt\\d+$/ (e.g. opt1)"),
    if: z
      .string()
      .regex(DeviceRegex, "device must be a VLAN (vlanNN) or a real NIC (e.g. igb0)"),
    descr: z.string().regex(DescrRegex, "invalid description charset").optional(),
  });

• src/tools/interfaces.ts:68-91 (registration)

  Tool definition registration for opnsense_if_assign. Declares name, description, and inputSchema with properties slot, if, and descr.

  {
    name: "opnsense_if_assign",
    description:
      "Assign an existing VLAN or NIC device to a free optN slot via SSH. Requires OPNSENSE_SSH_ENABLED=true and the opnsense-helpers/if_assign.php script installed on the target host. Fills the gap where the OPNsense REST API has no 'Interfaces → Assignments' endpoint.",
    inputSchema: {
      type: "object" as const,
      properties: {
        slot: {
          type: "string",
          description: "Target slot (e.g. 'opt1', 'opt2'). Must be free.",
        },
        if: {
          type: "string",
          description:
            "Device to assign (e.g. 'vlan10' for a VLAN or 'igb0' for a real NIC)",
        },
        descr: {
          type: "string",
          description: "Optional friendly description (max 120 chars)",
        },
      },
      required: ["slot", "if"],
    },
  },

• src/index.ts:62-62 (registration)

  Registration of all interface tool definitions (including opnsense_if_assign) into the tool handler map in the main server entrypoint.

  for (const def of interfacesToolDefinitions) toolHandlers.set(def.name, handleInterfacesTool);

• src/client/ssh-client.ts:168-195 (helper)

  The SSH runHelper method that executes the PHP helper script remotely. Used by the opnsense_if_assign handler to invoke if_assign.php on the OPNsense host.

  async runHelper(script: string, args: string[]): Promise<{
    response: HelperResponse;
    exitCode: number;
    stdout: string;
    stderr: string;
  }> {
    const remoteCommand = this.buildHelperCommand(script, args);
    const result = await this.runRemote(remoteCommand);
  
    let response: HelperResponse;
    try {
      response = JSON.parse(result.stdout.trim()) as HelperResponse;
    } catch {
      throw new SshClientError(
        `helper ${script} did not emit valid JSON on stdout (exit ${result.exitCode})`,
        result.exitCode,
        result.stdout,
        result.stderr,
      );
    }
  
    return {
      response,
      exitCode: result.exitCode,
      stdout: result.stdout,
      stderr: result.stderr,
    };
  }