This follows from the previous step, Adding Devices to Mudmap, if you have not added a device yet, be sure to read over that page first.
There is also a video demonstration, here
Now that we've got a device showing up in the table of Inactive Devices we have three options; Activate, Update or Delete.
A firewall that has been added but not yet made a connection with Mudmap will show up in the table like the image below.
To start the activation process is simple just click thebutton
Next, you will be prompted to enter the devices
root password. The pop up will look something
Mudmap does not store this password or log this information. A great number of things have been done to optimise the application so that your root password is not stored.
After entering the password. Mudmap will send a request to the firewall with the information you've previously supplied. This ensures that if any information is incorrect, or the device is unreachable, remediation steps can be conducted prior to the installation being attempted.
If Mudmap can authenticate with the firewall the user will be prompted to install the API on to the device.
Installation will start as soon as the user accepts the prompt. This may take a few minutes. Once the installation is complete a new alert with be displayed.
The device will now disappear from the table as it is no longer inactive and will appear on the dashboard home page ready to be viewed in detail.
If Mudmap cannot authenticate with the device it will send an alert notifying the user.
This could mean several things:
- Password is incorrect,
- Device details are incorrect,
- Network issues between Mudmap and the device,
- SSH is not enabled on the firewall
- A firewall rule is blocking the connection
In almost all instances, remediation starts with a user attempting to access the device manually.
Using the device credentials supplied to Mudmap, attempt to log in using the terminal or terminal emulator. If you cannot authenticate, double-check the information is correct.
A common reason for this failure is the firewall set to
Public Key only for SSH connections.
Read preparing devices for more details on why Mudmap needs Password access via SSH and when
it can be disabled.
If all the above steps fail, please contact me. The more information you are able to provide the easier it will be to debug the issue. Gathering logs from pfSense, particularly the ssh access logs, are invaluable, as is whether the device is virtual or physical. Issues on the Github page are also welcomed.
To update a devices details click thebutton
Entering wrong information, such as an incorrect IP address will result in a connection failure. This can be amended here.
Clickingwill pop up a new form pre-populated with the current information about the firewall. Simply change the required information and submit the form.
Your device will now have the updated data and if correct be ready for activation.
Deleting the device is as simple as clicking thebutton
This will delete the device from the database table inside Mudmap. Deleted devices can be re-registered at anytime. A recap on how to do that can be found at here.
The Activation Flow
Once the installation procedure starts Mudmap will step over several tasks, such as:
- Installing the API Agent
- Creating the
mudmapthe correct permissions
The agent installation, once complete, will refresh the pfSense GUI and create an API link inside the General tab. You are able to view the API in better detail there.
Altering the API settings, deleting the API or changing the
mudmap user account details
will in errors or even complete loss of connectivity.
When you have exhausted your free tier allocation, you will no longer able to access your devices detailed information, or make changes until subscribed or under the allocation.
To make a payment, go to the profile page. If you are not yet subscribed you will see a Subscribe button. Clicking this will open a Stripe page where you will be able to enter your payment details. Stripe is Mudmap's payment provider and handles all payment related details.
Once you are subscribed, you will have full access to Mudmap and be able to add as many devices are required. Mudmap is a pay as you go service meaning you will be charged only for the devices you're currently using. Note, added devices are not charged but activated devices are.
To see your expected monthly costs, open the Stripe portal in the profile page. It will take to a Stripe hosted page where you can also update payment details. Read more at the payments page in this documentation website.
After payment success, Mudmap will not prompt for payment again. Read more about how Mudmap calculates invoicing here.
Why Root password?
root access rights to do the initial installation onto the target device.
Acting as a super user, Mudmap is able to:
- Install the API Agent
- Create a
- Provision the
mudmapservice account permissions and install SSH public keys
Once complete, and the device successfully registers with Mudmap, it will no longer need this level of privileged access. Nor will it require password authentication ove SSH.
The password will not be saved or logged at any point.