Using the Multi-Instance Management GUI¶

The web-based Multi-Instance Management (MIM) graphical user interface (GUI) allows administrators to manage pfSense® Plus software installations registered with the controller.

From within the MIM GUI, administrators can get status information, configure instances, use remote consoles, and more.

Note

This document assumes the controller is already enabled (Multi-Instance Management Options in the pfSense® software GUI), configured (Multi-Instance Management Controller Setup), and has instances registered (Instance Registration).

Access the MIM GUI¶

Before proceeding, open the MIM GUI as described in Accessing the Multi-Instance Management GUI and login.

Tip

Accessing the MIM GUI on the controller will allow administrators to manage any instance registered with the controller. The MIM GUI on instances can only manage the local instance.

After logging in, the MIM GUI displays its dashboard.

MIM GUI Dashboard¶

The MIM GUI dashboard contains an overview of all instances managed by this controller.

Status Summary¶

The dashboard contains status summary items in the upper left.

The first status item reports the current controller memory usage, both in text form and as a gauge.

The second status item reports the total number of registered instances and their online status.

Note

The controller host itself is not included in the systems summary as it would be redundant – if the controller was offline, the dashboard could not be loaded.

Instance List Entries¶

The instance list in the dashboard contains an entry for every instance registered with the controller, plus the controller itself.

Each list entry contains several items indicating the status of the instance, management controls, and options.

../_images/mimgui-dashboard-device.png — Instance List Entry¶

Hostname:

The hostname of the instance is printed in the bar at the top of the instance entry at the upper left.

Address:

The IP address and MIM GUI port is printed in the bar at the top of the instance entry under the hostname.

Management Controls:

The upper right area of the bar at the top of the instance entry contains two icons to manage the instance:

: Opens a Remote Console on the instance.
: Enters the Remote Configuration interface for the instance.

Status Icon:

In the upper left of the main area of the instance entry is an icon indicating its status. Possible states include:

Online:
Error:

Device Type:

The first line of text in the instance body is the type of device. This can be a hardware model, hypervisor type, cloud provider, etc.

Version Information:

The current software version is printed under the device type.

Interface Status:

The instance entry contains a row of squares indicating network interface status for the device. Connected interfaces are green, disconnected or disabled interfaces are gray. Hover the mouse cursor over a square to see its name and link speed.

Tags (If present):

Entries can be classified via tags (Tag Manager). If an instance has assigned tags, they are printed here.

Entry Options:

The icon opens a modal dialog window with general options for this instance entry.

Remove Entry:

The icon deregisters (removes) this entry from the controller.

Instance List Filter & Sort¶

The list of instances on the dashboard can be filtered and sorted to locate and manage items easier. The options to filter and sort the list are in the upper right area of the dashboard.

In that area, the following options are available:

Filter:

This drop-down menu allows filtering the list by item type.

Sort By:

This drop-down menu sorts the items on the dashboard by a specific attribute.

The current sort options are:

Name:: Sorts by instance hostname.
State:: Sorts by online/error status.
Address:: Sorts by IP address.
Type:: Sorts by device type.

Tags:

Enter a tag name to filter the list so it only shows items matching a specific tag or multiple tags.

Sort Order:

The sort order icon toggles between ascending () and descending () sort order.

Tile View:

Clicking the icon switches the dashboard to tile view, which is the default.

Detail View:

Clicking the icon switches the dashboard to a detailed list view.

Dashboard ToolBox¶

The Dashboard ToolBox is located on the right side of the dashboard screen and contains several options to manage dashboard items.

This ToolBox can appear in two different ways as determined by the Controller Options.

It can be a floating bar pinned to the right side of the screen:

Dashboard ToolBox - Right Side Style¶
It can be collapsed behind a hamburger menu button:

Dashboard ToolBox - FAB Style¶

The available actions are the same in both styles.

The actions available in the ToolBox are:

: Register an instance with the controller (Instance Registration).
: Reload dashboard data.
: Open the Help menu which also contains the current controller data for use in the registration process (Instance Registration).
: Opens the tag manager which assigns tags to dashboard list entries (Tag Manager).

Tag Manager¶

Dashboard items can be tagged to allow filtering entries based on custom keywords. To assign tags to instances, open the Tag Manager from the Dashboard ToolBox.

The Tag Manager can add or remove tags from one or more instances as follows:

Click Select Devices
Pick devices from the list, or click Select All
Click in the Tags field
Enter a tag name
Press Tab, press Enter, or click out of the Tags field
Click the desired action: to add the tag to the selected instances, or to remove the tag from the selected instances.

Controller Menu¶

The Controller Menu is on the left side of the MIM GUI.

../_images/mim-left-menu.png — Controller Menu¶

At the top right of the menu are icons for controller messages () and controller options ().

At the bottom of the menu is an Overview area with a text summary of instances and their status, along with a count of users currently logged into the controller.

The main body of the menu consists of several areas of interest, including:

Dashboard:

The MIM dashboard (MIM GUI Dashboard)

Configure:

Configure an instance (Remote Configuration).

While configuring an instance, the menu lists its address in the menu.

Log:

View MIM controller logs.

Software:

MIM image and package management.

Accounts:

User authentication configuration. This configuration is linked to the pfSense Plus software User Manager on the MIM controller host.

Controller Messages¶

Click in the Controller Menu to view messages and alerts from the MIM controller.

../_images/mimgui-messages.png — Messages List¶

The messages can be filtered by type. Click Info or Errors to hide/show that particular type of message. If the type has a check mark icon, messages of that type will be included in the list. The window title bar contains a count of messages displayed in the current view, plus a total.

Click at the top right of the window to clear all messages.

Controller Options¶

Click in the Controller Menu to configure options which affect the behavior of the controller itself. This dialog window also contains some status information.

Options¶

The top area of the dialog contains options which affect the appearance of the controller GUI.

Theme Color:

Select one of the colors to change the GUI theme to a scheme based on the chosen color.

Dark Mode:

Toggles the GUI theme between light and dark mode.

ToolBox View:

Changes the appearance of the ToolBox on the right side of the page.

Right-side ToolBox:: Presents the ToolBox as a free-floating menu always visible on the right side of the page (Dashboard ToolBox - Right Side Style).
FAB Toolbox:: Hides the ToolBox behind a hamburger menu button which must be clicked to see the individual menu entries (Dashboard ToolBox - FAB Style).

Status Information¶

The middle portion of the window contains status information about the controller.

Build:: The current build of the controller software.
API Version:: The current API version used by the controller.
Host:: The hostname of the device running the controller.
Key:: The API key used by the controller.
CPU Load:: A graph of CPU load on the device running the controller from the last hour.
Uptime:: The amount of time the controller has been running.

Actions¶

At the bottom of the window are buttons to perform actions on the controller.

Sign Out:: Logs the current user out of the controller and returns to the login screen.
Restart Controller:: Restarts the controller software.

Window Controls¶

Certain functions in the MIM GUI present modal dialog windows which have window controls.

These functions include:

: Expand the current window so it fills the browser window.
: Close the current window and return to the previous page.

Managing Lists of Items¶

Some areas in the MIM GUI contain lists of items. These are found when configuring the controller itself or instances. Lists of items are managed in a similar manner no matter where they are located, though some lists have more options than others.

Per-item Actions¶

List entries may contain icons to act on individual rows.

: Create a new entry and add it to the list immediately below this row.
: Create a new separator bar below this row.
: Create a new item using the settings from this item as starting values.
: Edit this list item.
: Click and drag using this icon to move an item. Drop it in the new location.
: View settings which control this list entry.

Selecting List Items¶

Some lists allow selecting one or more items to perform actions. Certain lists also have a “Select All” toggle to change the selection status of all entries.

: This item is not selected. Click the icon to select the item.
: This item is selected. Click the icon to deselect the item.
: Some items in this list are selected, and some are deselected. Click the icon to select all items.

ToolBox List Actions¶

../_images/mimgui-toolbox-rules.png — List Management - ToolBox for Firewall Rules¶

When managing lists, the ToolBox may show one or more of the following icons.

: Create a new item and add it to the list.
: Reload data for this list from the controller or instance.
: Add a new separator row.
: Remove the selected item(s).
: Toggle the state of the selected item(s). For example, disable or enable the item.
: Copy the selected item(s) to another location. For example, copy firewall rules to another interface.
: View help information for the page or items.
: Open the tag manager.