Unimus 2.8.0 is here, bringing one of the most anticipated features in recent releases — Compliance reporting. This is a major addition that opens the door to automated configuration validation, policy enforcement, and continuous oversight of configuration and runtime state across your entire infrastructure.

Alongside this headline feature, we’re shipping a host of smaller improvements, UI tweaks, fixes, and the usual batch of newly supported devices. Let’s walk through what’s new.

Compliance Reporting

This release introduces our brand-new Compliance module — a key tool for teams focused on security, governance, and operational stability. The module is available exclusively in the Advanced license tier.

With the new module, you can now define your golden configuration standards, internal policies, or industry standards, and have Unimus automatically validate your devices against them. Every time Unimus detects a configuration change, or a change in the runtime state of your network, your devices are re-validated, making it much easier to catch runtime surprises and configuration drift, before they escalate into security gaps or operational headaches.

Compliance rules can be as simple or as complex as you need — from straightforward text matching checks against your golden config, all the way to multi-condition regex logic linked together with logical operators. Results are presented clearly on preset and device levels and are ready for audits.

For a deeper look — from preset structure to practical examples — explore our full Compliance Overview article, along with our detailed wiki articles.

Enhancements, bug fixes, and new device drivers

Device CLI improvements

The Device CLI had a few issues when running "full-screen" programs like vim, mc, etc. We have changed it to use xterm by default, and implemented full handling for full-screen apps, resizing, changing window modes (full screen vs. partial), etc.

It should now be an even more capable terminal emulator :)

Saved search queues

Saved Searches received a small but handy improvement. When running multiple Saved searches in parallel, queued searches now correctly appear with a QUEUED state in the Saved Searches screen. The Saved Search detail view now also includes a state indicator for queued jobs.

You can additionally change the maximum number of Saved searches executed in parallel — which defaults to 5 — using the -Dunimus.server.config-search.query-page-size configuration property.

API v3: tag expiration

The API v3 documentation now includes expiration information for temporary tags across the POST, PUT, and GET endpoints, keeping the documentation fully aligned with the temporary tags feature introduced in Unimus 2.7.1.

Expanded device support

This release also adds and improves support for a variety of platforms:

• New driver for Arrcus ArcOS, DNVP and Ribbon devices
• Expanded support for NetGear GS-series switches
• Expanded support for Aruba Mobility Controller
• And more - check the full Changelog...

As always, these additions make Unimus more capable across the increasingly diverse networks deployed today.

For the complete list of changes, including all minor features, fixes, and newly supported devices, see the full 2.8.0 Changelog below:

= Version 2.8.0 =
Features:
  Improved Config Search / Saved Search queueing system that allows queueing and running many searches in parallel
  When running many Config Searches / Saved Searches in parallel, a proper "Queued" status will be displayed for queued Searches
  Various minor UI / UX improvements (help texts, styling, etc.)
  Added support for more types of login banners during SSH login
  Added support for more keyboard-interactive password auth variations during SSH login
  Added support for more variations of login prompts over Telnet
  On WatchGaurd firewalls, admin sessions will be properly released before a CLI session is closed

  Improvements to live Device CLI (Devices screen):
    - Device CLI could misbehave when opening "full-screen" programs like vim, etc.
    - the Device CLI will now use xterm as the default terminal type
    - the Device CLI will now automatically scale and rescale with CLI window size changes
    - this should fix CLI working correctly with full-screen programs, when being resized, etc.

  Added a new Config Compliance feature:
    - Compliance is the hero feature of the 2.8 release, and the largest new feature we have released in the last 2 years
    - you can now create Compliance presets which will report if you Configuration is compliant with your policies
    - Compliance also supports checking Runtime-state compliance of your devices - check for runtime port security violations, etc.
    - this is a large and complex feature, we look forward to your feedback and improvements will be coming in point releases in 2.8
    - Feature Overview: https://blog.unimus.net/config-compliance-unimus-2-8/
    - documentation: https://wiki.unimus.net/display/UNPUB/Compliance+Reporting

  Added support for:
    - Arrcus ArcOS
    - Aruba Mobility Controller running v8 firmware
    - Aruba AOS-8
    - DNWP Connection Master
    - DNWP Dyna Wiz
    - Netgate TNSR
    - Netgear GS-series switches (GS752TP)
    - Nokia Lightspan MF
    - Ribbon NPT

Fixes:
  Fixed strange characters could be printed in Device CLI if specific locales were used on the server
  Fixed 'Create another device' checkbox in device creation could sometimes not work
  Fixed Discovery failing on specific versions and models of Juniper JunOS devices
  Fixed Discovery failing on RuggedCom switches
  Fixed Discovery failing on Alcatel switches
  Fixed consecutive jobs on WatchGuard firewalls failing due to admin session count limitations
  Fixed jobs failing on SonicWall with enabled login banner
  Fixed jobs could fail on Fiberstore (FS.com) 32xx switch series with specific pagination variations
  Fixed Backup failing on Digi WR44 due to missing prompt after backup output
  Fixed Discovery failing on Nokia Lightspan due to Lightspan's command echo format

Embedded Core version:
  2.8.0

Like it or not, IT infrastructure and its underlying networks exist in constant flux.

What starts as a clean, well-planned environment can - if left unchecked - slowly slip into something… less predictable. Device configurations drift, policies go stale, a temporary firewall rule added during troubleshooting might linger long after it’s needed, and the gap between “how things should be” and “how things actually are” quietly widens.

And that’s exactly where Compliance steps in to restore order.

Why compliance matters

Compliance isn’t an unnecessary administrative burden. It’s about knowing exactly where your network stands.

A network that is compliant to configuration rules & best practices delivers real, practical benefits:

• Configs stay consistent
• Policies remain enforced
• Troubleshooting is simpler and therefore faster
• Audit requests are manageable and don’t turn into a fire drill
• Attackers have fewer opportunities to exploit

And with standards like PCI DSS, ISO/IEC 27001 and the NIS2 Directive, having a controlled and monitored configuration baseline is no longer optional - it’s simply expected.

For all the reasons outlined above, Unimus 2.8.0 introduces the new Compliance engine — a highly requested addition to device configuration management. This module provides a structured way to automatically validate your network’s compliance at scale, whether you’re checking device configurations or monitoring live runtime state. With it, you can keep device configuration drift under control and ensure your network operates as intended. Read on for the full details.

How the new Unimus Compliance module works

Let's dive into the details. The new Compliance engine follows a preset-based structure, similar in spirit to Mass Config Push. Each Compliance preset defines a set of policies (rules and conditions), that Unimus checks against a chosen dataset and on specific devices.

Each Compliance preset is built from three parts: Source, Targets and Rules. Let's break down each of them below.

Preset sources

Source is the actual data you want the Compliance engine to validate.

You can choose from multiple source types:

Last Backup - the preset validates the most recent configuration backup (the current config running on the device).

Config Search result - the preset validates the latest configs of devices returned by a Saved Search.

Mass Config Push result - the preset validates device output produced by running an MCP preset.

Next, let’s look at how targets are determined.

Preset targets

Compliance targets are the devices being validated. Your selected data source affects how the targets are determined.

For presets where the Source type is Last Backup, you choose the targets directly - you can pick devices one by one, filter them by vendor or device type, or simply select by Tag.

When the preset source is set to Config Search result, the devices returned by a selected Saved Search become the targets. Only devices whose configurations match the search criteria of the Saved search are included. This is useful when you want to narrow the scope to devices that contain a specific configuration pattern - for example, to run checks only on devices that still use an old SNMP community, contain a deprecated ACL, or have a specific banner present in their backups.

When the preset source is a  Mass Config Push result, the targets are simply the devices targeted in that MCP preset.

With the sources and targets settled, we can turn to the heart of every Compliance preset - the rules.

Preset rules

Finally, rules define what the Compliance engine should look for in the chosen dataset (source). This is where the engine becomes really flexible. Each preset can include one or more rules, and each rule can include one or more conditions. You can create your own  compliance policies by defining conditions using:

• simple text-matching
• regular expression matching
• line-anchored checks
• combination of multiple conditions with AND/OR logic

Whether you need to enforce a specific configuration line, detect an insecure service, or confirm that an operational state is correct, these Compliance preset building blocks let you express the logic you need.

Continue reading to see how the new Compliance feature can fit into your workflow, with examples highlighting its flexibility and capabilities.

Examples and use cases

1. Defining a golden configuration

Let’s start with the most straightforward example.

Many teams maintain an internal “golden config” - a baseline device setup reflecting their operational and security standards. With Unimus, you can now define that baseline and have the system check against it.

Simply paste your expected configuration snippets into a Compliance condition, set the preset source to Last Backup, and define your target devices. Your condition might check for the correct firmware version, approved AAA servers, proper NTP servers, and logging. It could also enforce security hardening measures such as restricted SNMPv2 use, disabled insecure protocols like Telnet, removal of legacy ciphers, and strict password or authentication policies.

And with automatic execution enabled, the Compliance engine runs whenever a new configuration backup is generated for a targeted device.

With the preset in place, Unimus will continually review your latest configuration backups and flag any devices that drift from the baseline. No more combing through massive configs across hundreds of devices — the Compliance engine takes over, quietly keeping everything in check.

2. Beyond the golden config: Enforcing precise network policies

In addition to golden configuration presets, the Compliance engine lets you define flexible conditions using regular expressions, giving precise control over which configuration elements are allowed or disallowed on each device.

On the access layer of your network, you can enforce protections such as BPDU Guard or Root Guard for STP, making sure edge ports behave exactly as they should.

Moving up to the distribution and core layers, the engine can verify routing protocol security: OSPF or EIGRP authentication, proper route filtering, or that your IPv4 and IPv6 firewall states are in the expected shape.

At the edge or peering layer, you can validate BGP hardening — passwords, TTL security, session policies, and other controls that keep your network’s perimeter well-defended.

In this way, multiple checks can be combined for each device role, ensuring every part of your network aligns precisely with your policies.

3. Runtime compliance: validating your live network state

Compliance goes beyond just validating device configurations!

A valid configuration doesn’t automatically guarantee smooth operations. Configurations show how things should be — runtime data shows how things actually are. For example, your OSPF configuration may be correct, but how do you know your OSPF peers are actually up? Reviewing your latest configuration backups won’t help you here.

That's why Compliance Reporting also lets you validate live device output gathered through Mass Config Push / Pull, ensuring you have a precise understanding of your network’s current state.

Start by creating and scheduling a Mass Config Push preset targeting the devices whose runtime state you want to inspect. Even tho the feature in Unimus is called "Mass Config Push", we will use it to Pull data from devices in this case. The MCP preset should include the appropriate show commands that query the devices’ operating state.

Next, create a Compliance preset, enable Automatic execution, and select “Mass Config Push result” as its source, targeting your preconfigured MCP preset. Then define the rules and conditions that will evaluate the collected device output using text or regex matching. After each MCP run, the engine analyzes the latest runtime output from your devices and checks it against your Compliance rules.

This gives you visibility into the living, breathing state of your network, and because the system lets you define granular, fine-tuned conditions, the possibilities are remarkably rich — limited mainly by what you choose to monitor and the information your devices can provide through their CLI.

You can see whether your routing is healthy, BGP neighbors have dropped, OSPF is stuck in INIT, or EIGRP peers have gone missing. You can keep an eye on interface health as well: ports slipping into err-disabled, speed and duplex mismatches, rising error counters, or even devices running hot and experiencing high CPU utilization. The engine can also surface stack member inconsistencies in high-availability setups, failover activity, or sync issues.

And that’s just scratching the surface — the range of runtime checks you can create is virtually limitless, so explore them freely and tailor them to your specific needs.

Tracking compliance at a glance

Once your Compliance rules are set up and presets executed, how do you track the compliance state across hundreds of devices and multiple policies? You don’t have to dig through menus — a quick glance at the Device List shows whether everything is as it should be. For each device, Unimus displays a small compliance indicator in the Compliance column:

Green – device is fully compliant

Red – device is non-compliant

Yellow – source dataset is missing or invalid

Grey – device is unmanaged or hasn’t been checked yet

You can see per-preset Compliance state on the Compliance Home page.

But if you want to see the entire "battlefield" on one page, Unimus has you covered with the Compliance Matrix: every device laid out against every preset, making patterns and outliers jump out instantly. It’s especially useful when validating large-scale changes.

If you need more than a bird’s-eye view, you can drill down into the evaluation details. The Compliance engine validates compliance on multiple levels, letting you see exactly which condition caused a device to fail. For a deeper dive, check out our detailed wiki article.

What’s next?

Compliance Reporting in 2.8.0 lays the groundwork for broader compliance automation. In upcoming updates, you can expect Compliance notifications via email, Pushover, and Slack, as well as export options for HTML and CSV formats to support reporting and audits. We’re also improving the ability to search through rules and conditions, making it easier to manage complex presets.

As these features roll out, Compliance will continue to evolve, becoming an integral part of your everyday operational workflow.

Final words

Thanks for reading all the way through!

We hope this article has given you a clear overview of the robust and flexible Compliance Reporting module in Unimus 2.8.0, and shown how it helps keep your network aligned with both industry standards and your own company policies.

For a full, wiki-style documentation of the feature, check out our wiki article.

The Compliance Module is available in the Advanced Unimus tier as part of our new licensing model.

Lastly, if you encounter anything unexpected or have feedback, feel free to reach out via our forums or the usual support channels.

Until next time — stay on top of your networks, and keep your devices compliant.

Unimus 2.7.0 is here, and it's another major step forward. This release introduces three highly requested features – Saved Config Searches, Scheduled Config Searches and output filtering for Mass Config Push.

Alongside these, we’ve added a range of minor features, significant performance optimizations, various smaller enhancements, fixes, UI improvements, as well as the usual batch of newly supported devices. Let’s dive into what’s new in this release.

Saved Config searches

With this release, you no longer need to retype your frequent Config Search queries every time you want to run them. You can now save your frequently used Config Searches into a "library", and access them at any time. Just perform a search in Config search, click "Actions", then "Save search", and give the preset a name.

This addition makes Config search a significantly more powerful tool for recurring config lookups, audit reporting, and forensic or post-mortem analysis.

More info on Saved searches is available here.

Scheduled Config searches

Scheduled searches are now here!

When you save a Search, the results you see may be outdated the next time you visit it — the results are simply from the last time the search was ran. Now, you can apply a schedule to your searches so their results are always up to date and ready when you need them. No need for manual re-runs.

And there’s more coming: in Release 2.8.0, our brand-new Network Compliance module will arrive. The results of your scheduled searches will feed directly into it, enabling automatic validation of your network configuration and your configuration policies.

Stay tuned for more good stuff! ;-)

Filtering dynamic data in Config Push outputs

Mass Config Push just got a lot smarter. Before 2.7.0, even small dynamic variations - like timestamps or session counters - could cause Unimus to treat each Config Push output as a unique result. To address this, Unimus now supports applying Backup Filters to Mass Config Push outputs.

These filters clean up the noise by removing or ignoring dynamic data before results are grouped into unique output groups.

This means cleaner outputs, less visual clutter, and more accurate comparisons across your devices. Prefer raw, unfiltered output? Simply uncheck the “Apply backup filters to output” option in your Config Push preset Advanced settings.

More info on Config Push output filtering can be found here.

Performance optimizations

This release also brings major performance improvements across the board.

Config search has been completely re-engineered on the backend to use significantly less memory and deliver faster results - even in environments where you are searching in over 100,000 backups.

Downloading and exporting huge (1+ GB) search results is now memory-efficient, even when running with Unimus' default 768 MB memory limit, thanks to a new paging-based algorithm.

UI responsiveness has also been greatly improved, particularly for large device inventories. Previously, screens like the Devices table could lag when dealing with tens of thousands of devices, tags, and user access rules. With 2.7.0, we’ve reworked how access permissions are handled behind the scenes - resulting in page load times dropping from over a second to just a few milliseconds, even with huge inventories.

Bug fixes and security fixes

A long list of minor bug fixes accompanies this release, covering UI inconsistencies, rare discovery failures, and various edge-case issues.

We also addressed a few security issues, including cases where Zone IDs could appear in Config search results and where full API tokens could be exposed in debug logs.

As always, the goal is to ensure Unimus remains reliable in environments of any scale - from a few dozen devices to tens of thousands.

For a complete list of all changes, including 50+ minor features, bug fixes and improvements; 20+ newly supported devices; see the full 2.7.0 Changelog below:

= Version 2.7.0 =
Features:
  Added a counter for the number of backups of each devices in the Backups screen
  Device deletion logs now include the device IP address and Zone ID of the deleted device
  Added a Zone ID column to the tables in the Tag Devices and Un-tag Devices windows in the Tags screen
  Added device descriptions and Zone ID information to the Device Backup View window
  Added the Zone ID of a device in multiple notification and export messages where it was missing
  Improved the password reset process to properly indicate why a password can't be changed and if / when it was changed successfully
  Various minor UI / UX improvements and tweaks
  Added checking of Core configuration parameters - if you try to provide invalid Core config, a proper error message will be logged
  Added support for Config Sessions on Arista switches - Unimus will now properly close its Config Session on logout if they are enabled
  Added support for persistent management session slots on RAD Carrier Switches
  RAD Carrier Switch driver will now fallback to "info" if "info running" is not available
  Added support for newer firmware versions of Aruba APs (AOS-8)
  On Enterasys / Extreme switches session-based paging will now automatically be enabled on Unimus CLI sessions
  On Calix EXA session-based alarms will now automatically be disabled on Unimus CLI sessions
  Added support for partition in Config Push and Backup Flows for A10 Thunder Series
  Improved built-in dynamic filters for FortiOS devices

  Added a new Saved Config Searches feature:
    - you can save Config Searches you use often into the Saved Searches library
    - you can build your search library and quickly return to important or frequently used searches
    - Saved Searches can either be run manually, or they can run on schedule so you always have up-to-date results ready

  Config Searches can now be scheduled:
    - with addition of Saved Searches, searches can now also be scheduled to automatically run in the background
    - this means you can always have up-to-date results available in your Saved Searches without needing to run them manually
    - scheduled Saved Searches will also serve as one of the inputs into the Config Compliance feature coming in 2.8

  Backup Filters can now be applied to outputs of Config Push / Automations:
    - the Output Grouping feature of Config Push is super useful, but any dynamic data in device output (like timestamps) would cause it to not work
    - to solve this, you now have the option to apply Backup Filters to device outputs in Config Push before grouping takes place
    - more info: https://wiki.unimus.net/display/UNPUB/Filtering+dynamic+data+in+Config+Push+outputs

  Significant performance improvements:
    - large improvements were made in both application speed and memory usage - especially in large environments
    - the Dashboard will now load properly even with millions of job history records
    - login to Unimus will no longer be slow due to slow Dashboard load even in large environments
    - load speed of data in all tables and forms was also massively improved
    - improved Config search export to handle very large datasets reliably, preventing out-of-memory failures during export
    - rewrote the Config search engine to reduce memory usage and improve execution time

  Added support for devices which require a specific command to be sent before disconnection:
    - this is required on devices which keep persistent management sessions, and require a command to close them
    - this fixes an issue where running many jobs from Unimus in rapid succession could exhause the management session pool on these devices
    - in this release we added support for Arista switches with enabled Config Sessions and RAD Carries Switches with session persistency

  Added support for:
    - Alstom (KB) ElectroBlox
    - Alstom (KB) ElectroLogIXS EC4
    - Alstom (KB) ElectroLogIXS EC5
    - Alstom (KB) ElectroLogIXS VHLC
    - Alstom (KB) microWIU
    - Ansaldo STS MicroLok II VitalNet WIU
    - Cisco Secure Firewall for VMware
    - Digi TransPort WR44 v2
    - DZS (Zhone) MXK-F108
    - DZS (Zhone) V1-16XC
    - F5 F5OS based devices
    - Fiberstore (FS.com) switches running NetworkOS firmware
    - Fiberstore (FS.com) S3100 Series
    - HP(E) ProCurve Switch 4100GL series
    - Meteorcomm ARedge
    - Meteorcomm PTC 220 Base Station Radio
    - Nokia OLTs (MF-2)
    - Radware ADC
    - Radware LB
    - RUGGEDCOM RS900G Ethernet Switches
    - Siemens CNA-2000 Protocol Converter
    - Siemens Trainguard PTC Console
    - Ubiquiti UFiber OLTs with firmware version 4.9.0

Fixes:
  Fixed an issue where Dashboard load (and therefore also login) would be slow with very large job histories (millions of records)
  Fixed an issue where the Backup Retention Policy could remove even the current backup of a device
  Fixed an issue where successive opens of the Device Variable window would contain data for wrong devices
  Fixed an issue where diffs would not display lines ignored by Custom Backup Filters at all instead of showing the "<-filtered->" fragment
  Fixed an issue where empty lines used for spacing could be wrongly removed from Backups when using Custom Backup Filters
  Fixed an issue where the horizontal scrollbar was missing in the Credentials sections window during Credential Binding
  Fixed unnecessary errors in logs in some cases when a user logged into Unimus from the same browser as a different user
  Fixed ZoneID of a Device on the Device screen becoming N/A after adding a comment (visual issue only)
  Fixed an issue where running a Discovery job caused the Credentials table to refresh repeatedly
  Fixed multiple small UI / UX issues, inconsistencies, element misalignments, etc.
  Fixed Discovery would not work on some Cisco Catalyst switches due to a legacy IOS bug causing the configure prompt to end with "(confi)" instead of "(config)"
  Fixed Discovery would not work on Cambium ePMP devices (broken in 2.6.3)
  Fixed Discovery would not work on Fiberstore / FS.com S2805 series devices
  Fixed Discovery would wrongly identify Fiberstore / FS.com IES3110 series devices as Moxa devices
  Fixed Backup would fail on Fiberstore / FS.com IES 31xx series when pagination was enabled
  Fixed Discovery would fail on Cisco Firepower devices rebranded as Secure Firewall
  Fixed Discovery would fail on specific versions of H3C-based devices (specifically reported on Huawei NE8000)
  Fixed Discovery would fail on older UniFi switch models, including US-8, US-24, and USW-24
  Fixed Discovery would fail on Adit 600 series devices over Telnet
  Fixed Discovery would fail on Aruba 7205 controllers with an asterisk (crash dump indicator) in the prompt
  Fixed Discovery would fail on Aruba APs with latest firmware (AOS-8)
  Fixed issue with Arista switches with enabled Config Sessions where Unimus would eventually exhaust the device's available Config Session limit
  Fixed issue with RAD Carrier Switches with persistent management slots where rapid successive jobs would lead to management session exhaustion
  Fixed Backup would fail on Calix E7-2 EXA devices caused by session alarms / events interfering with the backup
  Fixed Backup would fail with INTERACTION_ERROR on F5 devices using the "imish" shell
  Fixed Backup would fail on Ubiquiti UFiber OLTs after upgrade to latest firmware
  Fixed Discovery would fail on Radware Alteon appliances running the latest firmware versions
  Fixed Discovery could miss-identify specific Cisco IOS XR devices incorrectly as Cisco IOS routers
  Fixed Discovery could fail on HP(E) ProCurve / ProVision switches in specific circumstances
  Fixed Discovery could fail on Aruba AOS and AOS-S switches in specific circumstances
  Fixed Discovery could fail on T-MARC devices if the "show system" command prompted for a password
  Fixed Backup of multi-context ASA firewalls could not back up some contexts with specific CLI settings
  Fixed Custom Backup Flows on A10 Thunder Series would fail if switching partitions
  Fixed Backup would fail on Enterasys / Extreme switches with large configs where the device could take 90+ seconds to even start outputting its backup
  Fixed Discovery of Calix BLC / OccamOS could fail in specific cases
  Fixed Config Push issue where very long commands executed on JunOS devices could result in an INTERACTION_ERROR
  Fixed Config Push issue that could cause invalid commands detection to fail in rare cases
  Fixed incorrect model identification for Fiberstore / FS.COM S3400 and S3900 (non-R) switches during discovery
  Fixed incorrect config change notifications for scep password and tertiary key hashes on FortiOS

Security fixes:
  Fixed an issue where the Zone ID of a device was visible in Config Search results for users without access to the corresponding Zone
  Fixed an issue where using invalid search criteria in Backup Filters would expose Filters which a user should not have had access to
  Fixed multiple cases where the full API tokens were displayed in debug logs

Embedded Core version:
  2.7.0

"Logs don't lie – they just patiently wait for you to finally listen."

Logs are the diary of any system, revealing what’s truly happening behind the scenes amid the chaos of day-to-day operations. They can – and often do – provide invaluable insights during debugging or troubleshooting sessions.

Today, we’ll look at where Unimus stores its logs and walk through how you can configure Unimus to relay its logs to a Syslog server of your choice. Whether you're troubleshooting, monitoring, or just want to keep all your logs in one place, setting up external log forwarding is a smart move. Let's get started!

Why centralized logging matters

Unimus logs contain valuable clues about your system's activity: including backup jobs, device discoveries, Mass Config Pushes, and more. Integrating these logs into your logging system can simplify troubleshooting by making it easier to correlate Unimus logs with logs from your network devices and other systems. It also streamlines log management, and improves visibility.

Not to forget, storing Unimus logs in both your local file system and an external Syslog server provides a valuable layer of redundancy.

Finding your Unimus logs

The Unimus Server writes log files to the following directories:

• Linux: /var/log/unimus
• Windows: C:\ProgramData\Unimus\log
  

Note: C:\ProgramData\ is usually a hidden folder.

That is pretty much all the essential information you need to get started. However, if you’re curious about the Unimus Logging Subsystem, you can check out our wiki page for more details about the content of Unimus logs, how to customize the logging level, or modify the log rotation settings.

Before you configure Unimus

Before configuring Unimus to send logs to your Syslog server, there are a few essential prerequisites to ensure a working setup.

1. Syslog server setup
Before proceeding, make sure that your Syslog server is:

• Enabled and listening on UDP port 514.
• Configured to accept and properly process Syslog messages from your Unimus server.

When it comes to choosing a Syslog server solution, you have plenty of options. Popular choices include the Linux-based rsyslog and Syslog-ng, or a platform like Graylog, a powerful log analysis solution. Alternatively, many Network Monitoring Systems (NMSes) also come with built-in Syslog servers or receivers, such as Zabbix, LibreNMS, PRTG, or NetXMS. If you’re already using one of these for collecting your logs or for even inventory synchronization with Unimus, it might make sense to forward your Unimus logs to the same destination for centralized log management.

2. Ensuring network accessibility
Next, verify that the Unimus instance can reach the Syslog server over the network. Make sure that any firewalls between your Unimus instance and the Syslog server are configured to allow traffic on the Syslog port (UDP 514). If this port is blocked by a firewall, the logs will never reach the Syslog server.

On Linux, the logger command is ideal for testing Syslog. Tools like Netcat or Nmap can help verify network reachability and whether UDP port 514 is open. Keep in mind that UDP is connectionless, so even if the port is open, you might not get a definitive success/failure unless something responds.

nmap -sU -p 514 <your_syslog_server_IP>
logger -n <your_syslog_server_IP> -P 514 -d "Test syslog message"

On Windows, tools such as Packet Sender, or Netcat can help you send test messages to a remote server over UDP 514. You can also use PowerShell with .NET classes to craft and send UDP packets manually.

Once you’ve completed the above checks, you can proceed with the steps below.

Configuring Unimus to relay its logs to a Syslog receiver

1. Stop the Unimus service.

2. Create a file named syslog-logging.xml in /etc/unimus/ (or C:\Program Files\Unimus\) with the following contents:

<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    <include resource="org/springframework/boot/logging/logback/base.xml"/>
    
  <!-- https://logback.qos.ch/manual/appenders.html#SyslogAppender -->
  <appender name="SYSLOG" class="ch.qos.logback.classic.net.SyslogAppender">
    <syslogHost>10.0.0.0</syslogHost>
    <facility>USER</facility>
    <suffixPattern>[%thread] %logger %msg</suffixPattern>
  </appender>

  <root level="INFO">
    <appender-ref ref="SYSLOG" />
  </root>
    
</configuration>

This is a custom Logback configuration file that tells Unimus how to send logs to an external Syslog server — including the destination IP log format, and Syslog facility.

3. Replace the syslogHost value with the IP address of your Syslog server. You can adjust other values, such as the suffix pattern or facility, as documented here:
https://logback.qos.ch/manual/appenders.html#SyslogAppender

4. For Linux deployments, add the following JVM options to the end of /etc/default/unimus:

-Dlogging.config=/etc/unimus/syslog-logging.xml -Dlogging.file.name=/var/log/unimus/unimus.log -Dlogging.logback.rollingpolicy.max-file-size=50MB -Dlogging.logback.rollingpolicy.max-history=9

For Windows deployments, add the following to C:\Program Files\Unimus\Unimus.l4j.ini:

-Dlogging.config="C:\Program Files\Unimus\syslog-logging.xml"
-Dlogging.file.name="C:\ProgramData\Unimus\log\unimus.log"
-Dlogging.logback.rollingpolicy.max-file-size=50MB
-Dlogging.logback.rollingpolicy.max-history=9

If you're running Unimus in a container, specify the above JVM options in the Docker Compose file instead, like this:

unimus:
    image: croc/unimus
    environment:
      - JAVA_OPTS=-Xms256M -Xmx1024M -Dlogging.config=/etc/unimus/syslog-logging.xml -Dlogging.file.name=/var/log/unimus/unimus.log -Dlogging.logback.rollingpolicy.max-file-size=50MB -Dlogging.logback.rollingpolicy.max-history=9
      - TZ=Europe/Budapest
    container_name: unimus
    ports:
      - "8085:8085"
      - "5509:5509/tcp"

Note that the above setups will relay the contents of the unimus.log file which can be found on a Unimus server.

If you wish to relay the logs from a Remote Core, edit the Core config file (/etc/default/unimus-core or C:\Program Files\Unimus\Unimus-Core.l4j.ini) and set the logging file parameter and specify /var/log/unimus-core/unimus-core.log or C:\ProgramData\Unimus-Core\log\unimus-core.log.

5. Restart the Unimus (or Unimus Core) service.

All done!

After the restart, Unimus will log both to /var/log/unimus/ (or C:\ProgramData\Unimus\log) and to the Syslog server specified in the syslog-logging.xml file. From this point on, every log entry written to the file system should also appear on your Syslog server.

Unimus not starting?

If Unimus fails to start, it's likely a syntax issue in your modified Unimus defaults file. Double-check for typos, unintentional or missing line breaks in the JVM options.

On Linux, make sure to place all the JVM options on a single line. On Windows deployments, each argument should be placed on its own line, and if the path argument contains spaces, wrap it in double quotes.

What's next?

Once the Unimus logs are flowing to your syslog server, the fun is not over. Modern Syslog collectors with log analysis capabilities let you go far beyond basic log collection.

You can correlate Unimus logs with those from routers, firewalls, and other systems to gain deeper insights. Want to detect when a Unimus server loses connection to a Remote Core? Create an event policy to trigger alerts or auto-generate tickets in your monitoring tools via API. Need to pinpoint the root cause of a BGP flap? Cross-reference Mass Config Push activity with network device logs. Focus on logs with severity levels 4 (WARN) and 3 (ERROR), as those specifically report problems that need attention.

With the right setup, your Unimus logs can become a rich source of operational intelligence, supporting you in troubleshooting when things go south.

Final words

Hopefully, this article has been helpful for those of you who’ve been looking for a way to set up log relaying in Unimus. If you have any questions or run into any issues that we didn’t foresee in this article, please feel free to post in the support section of our forums or reach out through our usual support channels.

Until next time, take care!

A new major feature release - Unimus 2.6.0 was released today! This release contains 3 major new features, 20+ minor features and enhancements, support for 19 new device types, and a healthy dose of bug and security fixes.

This article is an overview of the biggest changes and features in 2.6.0, but if you want to read up on everything that is new, you can find the full Changelog at the bottom of this article.

Device CLI

The biggest feature of 2.6 is a new terminal emulator directly in your Unimus web UI.

This gives you the ability to connect to the CLI of your devices directly from Unimus. The connection to Device CLI works seamlessly with our distributed deploy using Remote Cores, so you can easily connect to CLI of devices in remote networks with just a few clicks.

With this new feature, Unimus (on top of all the other features) also becomes a remote access gateway / jump host to all your device CLIs!

MFA (TOTP) support for Unimus login

Another new feature in 2.6 is support for TOTP-based MFA when logging in to Unimus.

For improved security, you can enable MFA, and it will be required when logging in to Unimus. This will work with all your usual MFA apps (or hardware TOTP MFA tokens).

In 2.6 we are adding support for TOTP-based MFA, but going forward we will be expanding this to support FIDO2-compatible hardware keys and passkeys in the future.

New "My account" screen

With the inclusion of MFA support, we also added a new "My account" screen.

Non-admin accounts (that don't have access to the User management screen) can change their own password here, assuming local auth (not LDAP/Radius) is used. Users can also set up their MFA here.

Database improvements and PostgreSQL v12+

Support for modern PostgreSQL versions is also finally here! We now support Postgre 12 through 17, while still keeping the existing support for 9 through 11.

We have also introduced separation for MariaDB vs. MySQL database drivers. During the Deploy Wizard, you will be able to select the exact version of your SQL database now. This will allow us to introduce flavor-specific optimizations into the DB layer of Unimus going forward.

We also published a full list of officially supported and tested DB versions on our Wiki: Database requirements

20+ minor enhancements and improvements

In addition to the features above, 2.6 also brings a few other minor new features and 20+ enhancements and improvements to existing features. A few of the notable ones are:

• Unified usage of server time (instead of browser local time) for the Backups screen, Diff screen and Config Change notifications
• Improved filtering of dynamic backup data when using Custom Backup Flows. Filters are now applied to outputs of each command, so you don't need to setup Backup Filters manually.
• You can now have multiple backup windows open in "Backups > Show" at the same time. No need to close and reopen windows anymore.
• Added a "Create another step" option in Custom Backup Flows creation for better UX.
• Support for post-login log messages on Lenovo switches, improvements to multi-context ASA handling, improved built-in backup filters.
• And much more...

Device support, bug fixes and security improvements

In 2.6, we are adding support for 19 new device types across 14 different vendors. Our full supported device list is now over 350+ various device types. Check the full Changelog below for the exact additions in 2.6.

As always, we are also fixing bugs, solving issues, and improving security. In this release over 25 issues got fixed, from annoying to trivial. More in the full Changelog below...

Finally, here is the full 2.6.0 Changelog:

= Version 2.6.0 =
Features:
  Added native support for MFA / TOTP for login to Unimus
  Added support for PostgreSQL v12 and newer (12-17)
  Users using local auth can now change their own passwords
  Unified usage of server time (instead of browser local time) for the Backups screen, Diff screen and Config Change notifications
  Multiple Network Scans when using the Embedded Core are now properly queued and executed in sequence
  Added a "Copy key" button to copy a Zone Access Key to clipboard
  Improved filtering of dynamic backup data in Custom Backup Flows, filters are now applied to outputs of each command
  Added separation between MySQL and MariaDB drivers in Wizard and config, and optimization for each
  Export windows will now automatically close after a successful export (Backup export, Config Search export, etc.)
  Configured context size for Config Search is also applied to Config Search Export
  You can now have multiple backup windows open in "Backups > Show" at the same time
  Added a "Create another step" option in Custom Backup Flows creation for better UX
  Improved handling of object ownership changes across the entire application
  Various minor UI / UX improvements and tweaks
  Added support for post-login log messages on Lenovo switches
  Added handling for multi-context Cisco ASA, if unable to switch to system context, just backup a single context instead of failing
  Improved log messages on failed device logins for easier visibility into failed jobs
  Improved device authentication algorithm when using SSH
  Improved sorting for random ordering of dynamic rules on Palo Alto PanOS when managed by Panorama
  Improved handling of failed mode switches in the Discovery algorithm
  Improved handling of password change requests during device logins (Unimus will detect this, cancel login, and show proper error)
  Added builtin support for the "Power Off the system ? [yes,no]" prompt (JunOS) in Config Push
  Added builtin support for the "Are you sure you want to continue connecting?" prompt in Config Push
  Improved builtin backup filters for Ericsson IPOS
  Improved builtin backup filters for IOS XR

  Added a new "My account" section:
    - users can change their own password if not using external auth
    - users can enable / manage MFA for their account
    - more per-account settings to be added to this screen soon
    - more info: https://wiki.unimus.net/display/UNPUB/User+accounts

  Added a new "Device CLI" feature:
    - you can now open a CLI session to your device directly in Unimus
    - this is a full web-based terminal emulator, making Unimus into a remote access gateway to all your devices
    - this can be disabled if desired: https://wiki.unimus.net/display/UNPUB/Disabling+specific+Unimus+features
    - full documentation: https://wiki.unimus.net/display/UNPUB/Device+CLI

  Added support for:
    - ArubaOS-CX Virtual
    - Broadcom Trident / Trident2 based devices
    - Cisco Catalyst 1300 series
    - Cisco IOS XRv / vIOS XR
    - Edgewater EdgeMarc
    - Fiberstore (FS.com) AC Wireless Controller
    - Fiberstore (FS.com) S3250
    - Fiberstore (FS.com) Wireless Switch
    - FreeWave radios (based on 900 series)
    - LDA Tech (LDAtech) MUX
    - Nokia WaveLite (based on Metro 200)
    - OcNOS-SP
    - OcNOS VM
    - Ribbon EdgeMarc
    - Supermicro SMIS modules and switches
    - Supermicro GEM (MBM-GEM, SMB-GEM) switches
    - Supermicro XEM (MBM-XEM, SMB-XEM) switches
    - Supermicro SSE switches
    - Telrad BreezeCompact (based on 1000e)
    - Versa SDWAN (VOS)
    - Wi-Tek (WiTek) switches

Fixes:
  Fixed notifications not working with private Slack channels
  Fixed issues where different time (browser vs. local) would be used for the Backup timeline vs. Diffs and Config Change notifications
  Fixed issue that could cause NMS Sync Rule Group IDs to be deleted when migrating from 2.5.0 to 2.5.1 (no other migration paths were affected)
  Fixed device presence in Zone in Network Scan would always be compared to the Default Zone, instead of the Zone selected in the Scan
  Fixed devices with "Planned" status being imported as Managed from Netbox / Nautobot
  Fixed a possible issue with migration of NMS Sync rules introduced in 2.5.1
  Fixed wrong examples in APIv3 documentation for a few endpoints
  Fixed built-in dynamic data backup filters would not be properly applied to outputs of Custom Backup Flows in some cases
  Fixed devices would take extremely long to delete if deleted during an ongoing job
  Fixed stopping a running Network Scan could take a very long time
  Fixed multiple Network Scans using the Embedded Core would not work properly
  Fixed Ownership updates not being propagated between concurrent users (live updates were missing)
  Fixed "Schedules > Show scheduled tasks" not being updated correctly on changes (live updates were missing)
  Fixed issues when trying to download an export of Config Search multiple times
  Fixed issue where Config Search export configuration could be ignored, and defaults were used
  Fixed config change notifications even when nothing changed on PA PanOS when managed by Panorama
  Fixed an issue when trying to sort by "Present in Zone" in Network Scan
  Fixed multiple small UI / UX issues, inconsistencies, element misalignments, etc.
  Fixed backups on Palo Alto devices could sometimes be empty, or only contain the backup command echo
  Fixed discovery failing on newer versions of ArubaOS-CX
  Fixed jobs failing on specific versions of IOS XR
  Fixed parts of device output missing in Config Push results in very rare cases
  Fixed HP(E) ProCurve / ProVision / ArubaOS failing discovery in specific cases
  Fixed Juniper JunOS devices could fail discovery in specific cases
  Fixed backups could fail on Ericsson SSR / IPOS in certain multi-context configurations
  Fixed backups could fail on Adva XG devices with specific firmware versions
  Fixed discovery failing on Quanta running on Broadcom Trident2
  Fixed Config Push could fail on Palo Alto devices in some cases

Security fixes:
  Fixed a rare case when switching a user to a restricted Role (like Read Only) would only be applied after the user logged out
  Fixed an already opened Device Info window would not be closed if user lost access to the device
  Fixed Operator-level users seeing the instance license key in Other settings
  Fixed users which did not have access to all devices in Zone being able to download all Zone logs

Embedded Core version:
  2.6.0

A new major feature Unimus release - 2.5.0 is finally here! This is a large release with lots of new features, enhancements, new device support, and a healthy dose of bug and security fixes.

This article is an overview of the biggest changes and features in 2.5.0, but you can also find the full Changelog at the bottom of this article.

Custom Backup Flows

One of the biggest features in 2.5 is the ability to create Custom Backup Flows. These Flows will allow you to specify your own sequences of commands to be executed during backup jobs on devices.

If you want to do backups on a device differently from our built-in flow (for example, add outputs of a few commands to be a part of the backup), up until now you didn't have a way to. Custom Backup Flows allow you to create your own backup procedures, so if you want to do a backup differently than our built-in flow, you now can.

You can find more info on Custom Backup flows, with more details and examples in this article on the Blog, or on our Wiki.

New Object Access Policies and improvements to user management

2.5 also brings a lot of improvements and changes to User Management and introduces new Object Access Policies.

Object Access policies replace Device Access rules (which existed before 2.5), and offer much better flexibility to define exact object access rules you need.

Together with new features like the Ownership system improvement and User provisioning (more on this below), the User Management system in Unimus receives a nice boost in 2.5.

For full info on what is new and what has checked, please check our Improvements to user management, provisioning and access policies in Unimus 2.5 on the Blog.

User provisioning (automatic new user creation)

Like we mentioned above, we have added an option to automatically create new users in Unimus when they successfully authenticate against an external AAA system for the first time. This allows for automatic user provisioning in Unimus.

After enabling this function, new users you create in LDAP / Radius can now login to Unimus without any manual user creation.

Ownership for Tags and Zones

We have extended the Ownership system to include Tags and Zones. We also added an option to show all objects owned by a particular user in the User Management screen.

These changes improve the overall access and security model in Unimus, and solve a few edge-cases where users could create new objects and immediately lose access to them due to access restrictions.

NetBox support in NMS Sync

Due to popular demand from the community (you!), we have added support for NetBox in NMS Sync.

Together with improvements to NMS Sync we introduced in 2.4, you can now sync your NetBox inventory to Unimus, sync object state and use NetBox as the source of truth for Unimus.

Tons of minor features and improvements

On top of the major features mentioned above, this release also contains over 20 minor features and improvements.

A few notable changes:

• Added option to create a new Credential directly in the Credential Binding window
• Tags can now be edited (you can change the Name or Owner)
• Added additional "Used by..." columns to the Tags table showing usage of Tags across Unimus
• Added a link to open the last failed job details to the "Device > Info" window
• Added an option to not show Unmanaged devices in results of Config Search
• Added an icon for credentials in High Security Mode to all relevant tables
• Added an option to specify your own Pushover API Key in Pushover settings
• Added an option to select the color scheme of diffs sent by notifications
• etc.

As always, we are also expanding the list of devices supported by Unimus. In this release, we added support for 12 new device types. Check the Changelog below for full info!

Bug fixes and security improvements

As always, we are also fixing bugs, solving issues, and improving security. In this release, we fixed 20+ bugs - from minor annoying issues all the way to jobs failing on various device types.

We have also focused quite a bit of attention on security. We have tightened the access restrictions for non-admin roles, but also fixed 10+ various security-related issues.

Please see the Changelog below for full info.

Finally, here is the full 2.5.0 Changelog:

= Version 2.5.0 =
Features:
  Device Tags have been renamed to just Tags, since they can be used on many more objects than just Devices now
  Tags can now be edited, allowing for change of Name or Owner (more on Ownership later)
  Changed default job concurrency (max number of parallel jobs) to 50
  When deleting a Zone, you can now choose to move devices to any other Zone you have access to before deleting the Zone
  Added an option to create a new Credential directly in the Credential Binding window
  Updated NetXMS client library to latest version (5.0.3)
  Added a Zone ID column to "Backups > Devices" table
  Added a link to open the last failed job details to the "Device > Info" window
  Added a notification banner to "Backup Filters" when user doesn't see all filters due to Access Policy restrictions
  Added a notification banner when trying to edit a Backup Filter when you don't have access to all devices covered by that filter
  Added a better message when a user with the "None" role attempts to log in
  Added additional "Used by..." columns to the Tags table showing usage of Tags across Unimus
  Added an option to not show Unmanaged devices in results of Config Search
  Added an icon for credentials in High Security Mode to all relevant tables
  Added an option to specify your own Pushover API Key in Pushover settings
  Added an option to select the color scheme of diffs sent by notifications
  Added a help popup to "Notifications > Show FQDN"
  Fixed various small UI / UX issues and UI element misalignment and sizing issues
  Changed Cisco ASA multi-context driver to only attempt backing up contexts when switching to the "system" context is possible
  Added support for offer prompts when a device offers multiple corrective options for invalid commands
  Improved handling of Nokia SROS / TimOS devices, fixing multiple issues in the process
  Improved support for Raisecom RAX / ISCOM devices (more device types now supported)

  Added new "Custom Backup Flows" feature:
    - you can now create presets that specify what commands are sent to Devices during Backup
    - you can also specify pre-backup commands, post-backup commands, and what is consumed as the backup content
    - if a Custom Flow exists for a Device, it will be used instead of the built-in flow in the Device Driver
    - you can target devices by Tag, Vendor, Type, etc.
    - more info at: https://blog.unimus.net/custom-backup-flows-in-unimus-2-5/

  Added support for NetBox in NMS Sync:
    - you can now sync your NetBox inventory into Unimus
    - import filtering based on "role", "tag", "location" and "field" (Custom Fields) is available
    - the "status" field in NetBox is used to set the Managed flag in Unimus
    - more info at: https://wiki.unimus.net/display/UNPUB/NetBox+importer

  Prefixes for filters in NMS Sync were replaced by a key-value system
    - until this release, entries in Sync Rules needed prefixes, with each prefix meaning something different
    - this was inconsistent across different Sync Connectors, and also quite confusing (you had to read docs every time on what prefix does what)
    - we replaced prefixes with a Key=Value system (for example "id=123", "group=routers", etc.)
    - existing Sync Rule configuration will be automatically migrated to the new system

  Device Access was reworked into Object Access Policies:
    - you can now create complex Object Access policies which specify where a user should have access to
    - Object Access Policies can then be assigned to users to limit object access across Unimus
    - existing Device Access rules will be migrated to new Object Access Policies automatically
    - more info at: https://blog.unimus.net/user-management-provisioning-and-access-policies-in-unimus-2-5/

  Added an option to create user accounts for users successfully authenticated by an external auth system:
    - this allows provisioning of users on first successful login to Unimus when using Radius / LDAP auth
    - using this system, you no longer need to create user accounts in Unimus for external AAA users before they can log in
    - both Role and Object Access Policy for automatically created accounts are configurable
    - more info at: https://blog.unimus.net/user-management-provisioning-and-access-policies-in-unimus-2-5/

  Object Ownership system has been extended to Tags and Zones:
    - Tags and Zones now have an "Owner" attribute, same as Devices
    - access to these objects can now be gained by being their Owner, separately from Object Access Policies
    - ownership has precedent over Object Access Policies - owners always have access to objects owned by them

  You can now see all Objects owned by a User in User Management:
    - new "Show object ownership" button was added in User management
    - this will show all Objects, as well as their types owned by this User
    - you can also remove ownership of Objects from this User in this window

  Improvements to APIv2 / APIv3:
    - added the zoneId attribute to all Devices and Diff APIv2 endpoints
    - added the zoneId attribute to multiple response objects in APIv3 where it was missing

  Added support for:
    - Cisco IOL (IOS on Linux) switches
    - Cisco IOL (IOS on Linux) routers
    - CheckPoint Gaia running on bare metal
    - CheckPoint TE series
    - CheckPoint QLS (Quantum Light Speed)
    - iS5 IMX devices
    - iS5 iES devices
    - Netonix WS3 switches
    - Racom RAy
    - Raisecom REAP OS devices
    - Ruckus vSZ-H
    - SONiC OS

Fixes:
  Fixed Config Change notifications would not apply Backup Filters in the notification diff when a new changepoint was generated
  Fixed importing valid .csv files with formatting errors could result in a stuck Import job
  Fixed "Export Diff" ignored the "Only changed lines" checkbox, and always sent only changes
  Fixed selection model breaking in the Credentials table after editing a Credential
  Fixed issues when changing large amount of objects (2000+) in a single operation when using MSSQL
  Fixed multiple other object manipulation failures when using MSSQL (Device Zone change, etc.)
  Fixed selected Zone disappearing from the Zone selection dropdown in "Basic import" after a successful import
  Fixed config change notifications even when nothing changed on PA PanOS when managed by Panorama
  Fixed issue in API with Zones which had a NetXMS Agent selected as their Connection method
  Fixed Mass Config Push > Advanced Settings allowed setting an empty value for Override Timeouts
  Fixed live updates there were missing in multiple screens, tables, and "used by" counters
  Fixed many various minor UI and UX issues and inconsistencies
  Fixed wrong / extraneous logging during the database upgrade stage when updating
  Fixed OPNSense jobs failing when device presented a menu after switching to root
  Fixed discovery failing on Ericsson SGSN in specific cases
  Fixed multi-context backup failing on Ericsson IPOS in specific cases
  Fixed a few specific Cisco router models being identified as switches
  Fixed backup failing on Cisco routers that were incorrectly identified as switches
  Fixed discovery could fail on Nokia SROS / TimOS devices on specific version
  Fixed backup and Config Push could fail on Nokia SROS / TimOS devices on specific version
  Fixed backup and Config Push could on specific version of NetElastic vBGN
  Fixed Cisco ASA backup failing when logging into a context without the ability to switch into the "system" context
  Fixed more cases when jobs could fail on Checkpoint Gaia devices

Security fixes:
  Only Administrator-level users can now change Notification settings
  Only Administrator-level users can now change Retention settings
  Only Administrator-level users can now change Advanced System Settings
  NMS Sync Presets where "Device Action policy" is set to "Move from All Zones" are now read-only for Users who do not have access to all Zones
  Users who do not have access to all Zones can not select the "Move from All Zones" in "Device Action policy" when creating a new NMS Sync Preset
  Users will not see an NMS Sync Rule if they don't have access to the Zone selected for that Rule
  For Presets using Tags (Config Push, Backup Filters, etc.), only Users with access to all Devices under that Tag can manage the Preset
  Users can no longer edit Credentials that are used on Devices they don't have access to
  Users can no longer edit CLI Mode Change Passwords used on Devices they don't have access to
  If a User doesn't have access to all Devices in Unimus, they can no longer change the Default Schedule
  Users can no longer delete a Schedule if they don't have access to all Devices that use that Schedule
  Fixed cases where Users could see Backup Filters even for Devices they did not have access to
  Fixed Users could still see and modify Targets in Config Push if Object ownership was modified concurrently

Embedded Core version:
  2.5.0

With the 2.5.0 release, we are bringing a lot of improvements and changes to User Management and Access Policies in Unimus. We are also adding the ability for User Provisioning from external AAA sources (LDAP or Radius).

In this post, we would like to walk you through what is new, and what has changed.

How user management and security worked before 2.5

We've had full role-based access controls (RBAC), as well as per-object access policies in Unimus for a long while now. We also have support for external auth (AAA) from LDAP and/or Radius.

How this worked is that you would first setup your external AAA connector - either LDAP or Radius (assuming you wanted to use external AAA).

Then you would create a local Unimus user. You would set this user to use your preferred auth method, either local, or external. You could also assign a Role for your user, limiting them to specific actions (more info in our Role documentation).

After the user was created, you could then limit which objects they have access to in Unimus using the Device Access rules. By default, users would have access to all devices, and you could restrict that access to only devices with particular Tags.

Using the combination of roles and Device Access rules, you could achieve control of both what users can do (limit their actions), as well as which objects they can see and perform actions on.

Why are we changing this

The existing system had a few limitations. In particular:

• A local Unimus user had to exist before they could auth from an external auth source. This means that even if you were using LDAP as your auth source, when adding a new user, you would still have to log in to Unimus and create a local user and set it to auth from LDAP. This was a little tedious.
• During a new deployment in large networks, even if you had a single central auth source, you still needed to create all users in Unimus locally (related to previous point).
• Due to how Device Access rules worked, you could not, for example, create a rule which gave access to all devices other than a particular device set.
• The Ownership system was only applied to Devices, so users could create other objects and immediately lose access to them due to their access rules.
• You had no way to see all objects owned by a User.

In 2.5.0, we hope to solve all these issues.

What is new in Unimus 2.5

To solve the issues described above, we have made 3 major changes to the user management system in Unimus:

• We have reworked Device Access rules into Object Access Policies.
• We have extended the Ownership system to now cover not just Devices, but also Tags and Zones.
• We have created an Automatic User Creation system, which can be used for easy User provisioning.

Let's look at each of these in detail:

Object Access Policies

Device Access rules have been replaced by Object Access Policies. A Policy has 2 components, a "base access" component and optional exceptions.

There are 2 base access policies:

• All objects
• No objects

You can combine these base policies with Tag-based exceptions, to create a custom access policy that covers exactly the objects you need.

First you need to create a policy:

After creating a policy, if it has exceptions, you can select which Tags are applied as the exception. In the example below, the user to which this policy would be applied would only have access to objects tagged by the "Routers" Tag.

This is because the base policy is "No objects", but there is an exception for the Routers Tag, allowing access to those objects.

All of your existing Device Access rules will be converted to the new Object Access Policies automatically after you upgrade to 2.5.0. You can find more info on Object Access Policies in our documentation on our Wiki.

Ownership for Tags and Zones

We have extended the Ownership system to include Tags and Zones:

We also added an option to show all objects owned by a particular user:

Automatic User Creation (User provisioning)

Finally, we have also added an option to automatically create new users in Unimus when they successfully auth from an external AAA system for the first time. This allows for automatic user provisioning in Unimus.

You can select both the Role, as well as the Object Access Policy you want the new users created with, so you can easily secure these new accounts, and elevate their permissions if needed.

The configuration is very simple:

After enabling this function, new users you create in LDAP / Radius can now login to Unimus without any manual user creation.

Final words

We hope these new features and options add more flexibility and options to our (and your) security model, and simplify user creation and management for you. If you run into any issues, or want to let us know if anything is missing, please head to our forums, either the support section or the feature request section, and let us know!

The new user management functions are available starting with Unimus 2.5.0. Please head over to the Download section to download the latest Unimus release.

We are adding the ability to create your own Custom Backup Flows in Unimus 2.5. These Flows will allow you to specify your own sequences of commands to be executed during backup jobs on devices.

When will Backup Flows be useful?

Up until 2.5, how a Device Backup is performed is hard-coded in Device Drivers built into Unimus. When we add support for new devices, we implement a Backup Flow inside the Device Driver. This assures that all devices on our list of supported devices behave consistently and work out of the box.

However, if you would like to do backup on a device differently from our built-in flow (for example, add outputs of a few commands to be a part of the backup), up until now you didn't have a way to. Custom Backup Flows allow you to create your own backup procedures, so if you want to do a backup differently than our built-in flow, you now can.

Custom Flows vs. Built-in Flows

As we mentioned before, Custom Flows will override built-in Flows for devices which have a Custom Flow assigned. You can target devices either by their Vendor, Device Type, or by Tags.

Since there are multiple ways to target devices with Custom Flows, it is possible to create "conflicts", where more than one Custom Flow exists for a device. If a conflict like this exists, Unimus will execute the default Flow built in the Device Driver.

To check if there is a Flow conflict on a device, you can navigate to the Devices screen, select the device, click Info > Backup Flows. A table will show all Flows assigned to this Device. If there is more than one, you have a conflict on your hands.

How do you define a Custom Flow?

A Backup Flow is a sequence of steps performed on a device. As such, for a Custom Flow you need to define these steps yourself. In the Flow creation window, you can click Add step, and select the step type:

There are options to switch the device into Enable (privileged-exec) or Configure mode. This works in a very similar way to Config Push. You can see more info on modes here: https://wiki.unimus.net/display/UNPUB/Device+mode+table.

The most used step type is the Send command. This step will send the command you provide to the device. You can then choose if the output of this command should be consumed into the final Device Backup. You can also choose whether this command failing should fail the entire Backup job, or if the failure should be ignored, and next step should be executed.

If you just want to run some pre and post-backup commands, you can simply set them to be excluded from the final backup.

Example

Here is an example of how a complete Custom Backup Flow might look like:

• First we will log in to the device and make sure it is in Enable (Privileged Exec) mode.
• Then we send terminal length 1000, just so there is less pagination in output of future commands. Altho Unimus has no issues with pagination (and will remove it from output properly) on some devices it may be useful to turn off pagination completely. You can notice we don't include the output of this device in our backup (Exclude output from Backup is set to true).
• Then we send our main show running-config backup command.
• After getting the config, we do mutliple additional show ... commands, and include those in the device backup. You can notice we set Ignore failure to true, so if any of these additional commands fail, we won't fail the entire backup, and just ignore the failure.

The result of this Backup Flow will be a single device backup, containing outputs from show running-config, and all the additional show ... commands we listed. Since we target all EdgeSwitches in our network, when Backup will be run on any EdgeSwitch, our Custom Backup Flow will be used instead of the built-in driver flow.

How to debug failing Backups

Finally, we want to show you how you can debug failing backups when using Custom Flows. You can easily see what's happening during a Device Backup using our Debug Mode options. Please head to Zones and enable Device Output Logging for the Zone your devices are in:

After the debug is enabled, you can run a backup on the device which fails. After the backup job fails, you can download the device output log:

In the log, you will see full CLI communication with the device, and should be able to spot why the backup fails.

Final words

We are introducing Custom Backup Flows with the hope that this will give you flexibility and customizability to backup your devices in any way you need. If you run into any issues, or want to let us know if anything is missing, please head to our forum, either the support section or the feature request section, and let us know!

Custom Backup Flows are available starting with Unimus 2.5.0. Please head over to the Download section to download the latest Unimus release.

A new major Unimus release - 2.4.0 is finally here! With it come new features, reworks and improvements, new device support, and as always, bug fixes. This article is dedicated to the highlights of the 2.4.0 release, and the full Changelog is available at the bottom.

We have also published a video overview on our YouTube channel:

Mass Config Push macros overhaul

Mass Config Push is a powerful Unimus feature for automation made even more versatile when used with macros. Macros (modifiers, actions and user variables) allow you to build complex configuration deployments, firmware upgrade procedures or maintenance tasks.

In 2.4.0 the modifier syntax was changed to a "$(modifier-name yes/no)" format in order to minimize overall ambiguity and new modifiers "fail-on-error" and "wait-echo" were added. Format used for all actions is now "$(action-name value)". A new delay "action" was also introduced which simply waits for a specified time. Positions within a line for modifiers and actions are now enforced. Check out the wiki for more info.

NMS Sync enhancements

The old NMS Sync logic served well for three long years, though it wasn't without its shortcomings. The robust rework introduced in 2.4.0-Beta5 handles syncing from any combination of different systems or different instances of the same system.

We've introduced the concept of device orphaning in order to track changes on the NMS. A device becomes orphaned when it is no longer being provided by the NMS. This is useful in reflecting on Unimus the current state of the remote NMS that is being synced.

Two new settings were added to the NMS Sync Preset configuration to accommodate the flexibility of the Sync logic. Device Action policy controls creating new devices versus moving existing ones to a target Zone described by a Sync Preset Rule. With Orphaning policy Unimus can keep, unmanage or delete orphaned devices at the end of a Sync.

Tl;dr: NMS Sync now handles added, changed, removed and disabled devices in virtually any complex setup and will create / move / delete or disable local devices to reflect the state on the NMS. The full NMS Sync rework rundown can be found in this blog article and on our YouTube channel.

SSH handling support

Multiple improvements were made on the SSH connection establishment and session stability. Among few examples are:

• Devices which don't play well when "none" SSH auth method is offered are now supported.
• Login banner recognition has been adjusted to handle the quirkiest of banner types.
• SSH version validation timeout can now be overridden to accommodate device types that need a little extra time to respond. Details in configuration documentation on our wiki.

Zabbix and LibreNMS connectors

By popular demand we've added an option to import Zabbix hosts by their assigned Templates and Tags, using '%' and '@' prefixes respectively. Existing Sync Presets will continue working as expected. More info in the Functionality > Import > Zabbix section on the wiki.

We have also added new "Address field priority" and "Description field priority" selectors for LibreNMS. These allow you to configure which fields from Libre are pulled into device information in Unimus.

Other features and new device type support

Minor features such as the obligatory NetXMS client library update, improved built-in backup filters, UI/UX touch-ups and Zone support hot-fix for APIv2 come included in the 2.4.0 package.

23 new device types joined the list of devices supported by Unimus in this release. Full Changelog below for more info.

Fixes of various shape and form

Wouldn't be a major release without a healthy dose of bug fixes. One to mention is Remote Core connections could be seen as up, even after they were closed, which prevented the same Remote Core to reconnect.

One security fix applied involved read-only users being able to add a new Zone.

Finally, here is the full 2.4.0 Changelog:

= Version 2.4.0 =
Features:
  Updated NetXMS client library to latest version (4.4.4)
  Added filtering of log messages inside Cisco SMB switch backups
  Added a built-in backup filter for new timestamp format in MikroTik RouterOS v7.10
  Improved built-in backup filters for newer versions of Ubiquiti EdgeSwitch X
  Improved handling of errors for Zones which use a NetXMS Agent as the Zone's proxy
  Added possibility to search by Credential Type in "Credentials > Device credentials" table
  Various minor UI and UX fixes and improvements
  Added support for devices which don't respond to the "none" SSH auth method
  Improved login banner recognition logic, more banner types are now supported
  If a DNS lookup for a device hostname fails, this will now be reported as an exact job failure reason
  Added support for session restoration prompts after login (for example on Cisco ISE)
  Added support for CLIs which don't echo the "?" when receiving commands like "show ?"
  Added the option to override the SSH version validation timeout (new "unimus.core.ssh-version-validation-timeout" setting)
  Added support for multi-partition backup on F5 devices
  Added support for all possible formats of user and root prompts in OPNsense
  Added support for output termination in newer versions of VyOS
  Added support for Cisco SMB switches which don't report their model on the CLI
  Added support for Linux shell login on netElastic vBGN
  Added support for output termination in paged output on netElastic vBGN
  Improved support for Adtran NetVanta devices
  Improved support for logins to JunOS in BSD mode
  Improved handling of quoted strings on MikroTik RouterOS v7
  Added support for paginated output on RAD devices
  Added support for backup multipliers in the Cisco WLC driver
  Improvements to the CLI mode change algorithm (better handling of specific edge cases)
  Improved handling of error messages when Unimus config file is missing

  Config Push modifiers were improved and reworked:
    - modifier syntax was changed to a "$(modifier-name yes/no)" format
    - enforced modifier and action positions within a line
    - added support for new modifiers "fail-on-error", "wait-echo" and their opposites (yes/no)
    - added support for a "delay" action, which simply waits for a specified time
    - all existing Config Push presets should be migrated to the new syntax automatically
    - full documentation: https://wiki.unimus.net/display/UNPUB/Mass+Config+Push

  Major improvements to NMS Sync:
    - devices no longer present in NMS can now be automatically Unmanaged / Deleted in Unimus
    - improved tracking of which local device corresponds to which NMS device, allowing to move devices locally when they are moved in the NMS
    - if a device is not found locally in the target Zone, you can now specify if Unimus looks for a candidate to move into the Zone, or creates a new device
    - allow specifying what scope Unimus searches in for move candidates when trying to move devices across Zones
    - fixed multiple issues that arose in setups where multiple NMSes were being imported from into the same Zone
    - more info at https://blog.unimus.net/new-nms-sync-logic-2-4-0/

  Improvements to the Zabbix NMS Sync connector:
    - added support for importing from Templates and Tags on top of existing options
    - introduced new prefixes for various import sources
    - existing Sync Presets should be migrated automatically, and continue working as expected
    - full documentation: https://wiki.unimus.net/display/UNPUB/Zabbix+importer

  Improvements to the LibreNMS NMS Sync connector:
    - added "Address field priority" selector, allowing to specify how Unimus pulls device addresses from Libre
    - added "Description field priority" selectors, allowing to specify how Unimus pulls device descriptions from Libre

  APIv2 improvements:
    - add optional query param to select zone for the "findByAddress" endpoint at "api/v2/devices/"
    - add option to specify Zone for the "createDevice" endpoint at "api/v2/devices"
    - add option to specify Managed State for the "createDevice" endpoint at "api/v2/devices"
    - add option to specify Managed State for multiple GET and UPDATE endpoints at "api/v2/devices"

  APIv3 improvements:
    - added possibility to search by "usedByDevices", "boundToDevices" and "credentialsTypes" in "api/v3/credentials" endpoint

  Added support for:
    - Adtran NetVanta chassis
    - ADVA FSP 1xx series
    - AricentOS devices
    - more variants of the Aruba Mobility Controller
    - Calix AXOS
    - Calix E7-2
    - Cambium cnPilot
    - Casa vCCAP
    - Cisco Catalyst 1200 series switches
    - Cisco ISE
    - ComNet Switches (based on CNGE11FX3TX8MS)
    - EdgeCore 7316
    - EdgeCore CSR320
    - Ericsson IPOS (SSR series)
    - Ericsson SGSN
    - F5 multi-partition
    - Grandstream GWN7800 series switches
    - improved netElastic vBGN support
    - Opengear Operations Manager
    - Radware Alteon
    - Ruckus vSZ-D
    - Ruckus vSZ-E
    - TRENDnet TI switches
    - Westermo L110
    - Westermo Lynx-5512
    - Westermo RedFox-5728
    - Westermo WeOS

Fixes:
  Fixed inter-connection delay was not applied for Telnet service availability check
  Fixed logs present in backups on Cisco SMB switches (would trigger new change-points and change notifications on every backup)
  Fixed NMS Sync from Zabbix versions 6.2.1 and newer within 6.2 was not working (6.4 and older than 6.2 worked properly)
  Fixed for Zones which use a NetXMS Agent as a proxy all tasks within a job would fail if a single tasks failed
  Fixed inter-connection delay was not applied for NetXMS TCP proxy connections
  Fixed elements in combo box sometimes appearing multiple times in multiple screens across the application
  Fixed elements in combo box sometimes missing in multiple screens across the application
  Fixed beginning of lines could be truncated in diff the view on specific browser configurations
  Fixed reporting wrong Last Job Status for unmanaged devices over API (multiple APIv2 "/devices" endpoints)
  Fixed attempting to input a very long FQDN into the DB address during the Deploy Wizard was not possible
  Fixed Credential usage could be counted twice if a credential was used for both for SSH and Telnet (Credential > Usage screen)
  Fixed CLI Mode Change password usage could be counted twice if a credential was used for both for SSH and Telnet (Credential > Usage screen)
  Fixed an error that could occur if you switched screens while multiple popup windows were opened
  Fixed the possibility to input extremely long strings into dropdowns, which would eventually trigger an error
  Fixed Config Push triggered via API with an empty device ID string would create a wrong entry in Push results
  Fixed Delete Push Job History retention job was not re-scheduled when default schedule is changed
  Fixed issues with Config Push presets being deleted while they were opened in another browser window
  Fixed various minor UI and UX issues and inconsistencies
  Fixed jobs using Telnet could randomly fail
  Fixed login to devices could fail if certain login banners were used
  Fixed Remote Core would not be able to reconnect to the Server in specific cases
  Fixed Remote Core connections could be considered still alive even after the connection was closed
  Fixed jobs on Cambium 450i would always fail
  Fixed jobs on newer versions of VyOS failing
  Fixed login failing on specific Palo Alto devices
  Fixed specific commands on Aruba Mobility Controller (ArubaMM) could cause a Config Push to fail
  Fixed backups could fail on Cisco WLC under heavy load, or with very large configs
  Fixed jobs on specific Moxa switch types could randomly fail
  Fixed jobs on specific RAD devices would fail
  Fixed jobs on specific Adtran NetVanta devices would fail
  Fixed discovery failing on OPNsense with specific account and shell type combinations
  Fixed discovery would fail on JunOS devices with specific BSD prompt format
  Fixed discovery would fail for specific versions of the Aruba Mobility Controller
  Fixed sporadic config change notifications on MikroTik RouterOS v7

Security fixes:
  Fixed read-only users could add a new Zone
  Fixed Credentials and CLI Mode change passwords could be printed to the log file in cleartext on specific API calls

Embedded Core version:
  2.4.0

Migration warnings:
  On MikroTik RouterOS v7, you can get a single config change notification due to changes in how quoted strings
  are handled in our ROSv7 driver. This config change should only happen on the first backup job after upgrade
  and can be ignored.

The Unimus 2.4.0 release brings a complete rewrite of the NMS Sync feature logic. It gives you more options and control over Sync behavior, with minimal complexity added to the user experience.

The key addition to the functionality is device orphaning. Its role is to keep track of changes in device presence and state provided by the import source (NMS). Device additions, changes or removals are now automatically reflected in local inventory (Unimus).

There are two new settings to notice in the GUI of NMS Sync Preset configuration. These control Device action policy and Orphaning policy described in detail in sections below.

Lastly, we have also added two new group identifiers for Zabbix. We can now select devices to import that are using specific templates and/or tags by prefixing their names by '%' and '@', respectively. Host groups are used as before without any prefix.

Showcase of new features

In case you prefer a video format, you can watch an overview of the changes here:

How it works

The NMS Sync is a feature for importing devices into Unimus. Synchronization of devices from NMS systems automates the adoption of new networks into Unimus and simplifies device management by delegating the task entirely to the NMS (no need to manage devices across both Unimus and the NMS separately).

Since 2.1.0 the NMS Sync configuration is Preset-based, where each Sync Preset defines from which NMS to sync which devices into which Zone(s). The rework in 2.4.0 expands the Preset-based mechanics by Preset adoption. Each device imported by an NMS Sync Preset is now adopted by that given Sync Preset, allowing consistent identification of synced devices.

NMS Sync takes a device set provided by import source (NMS) and mirrors it in the local inventory (Unimus). Let's take a look at steps needed for a run-of-the-mill setup of an NMS Sync Preset:

1. Create NMS Sync Preset of your NMS type specifying URL and credentials
2. Create a Sync Rule specifying which groups of devices in the NMS should be imported
3. Specify this Rule's target Zone to import devices into
4. Go to step 2 if you want to define another Rule
5. Leave other settings at default values
6. Run and/or schedule the NMS Sync

After an NMS Sync runs its course it is considered successful if there were no errors or failures, otherwise it goes into the 'Failed jobs' bucket. Detailed report of either can be viewed in 'Dashboard > Import job history'. There we can find all the information about the import source, sync errors, processed, imported, updated devices and failed operations counts.

The nature of the beast

Unimus currently supports seven different NMSes. You may create Sync Presets with different systems and sync to the same Zone or you may have different instances of the same NMS and sync to different Zones. These systems may or may not support universally unique identifiers (UUIDs) for devices. You may even want to move devices between Zones manually and still be sure of what happens to them following an NMS Sync.

The logic needed to behave consistently during any changes, be it on the NMS, in Sync Preset Rules configuration or other settings in Unimus. It also needs to account for devices with matching address within and outside of a Sync Rule target Zone. Suffice to say the logic rework turned out to be quite the undertaking.

The following sections take a closer look at concepts, behaviors and policies introduced with the NMS Sync rework.

Remote UUIDs

As mentioned before, some of the NMSes Unimus supports provide UUIDs for devices during a Sync operation. These uniquely identify previously imported devices, enabling more consistent device tracking between Unimus and the remote systems. As an example, when UUIDs are used, changing device IP address of a host on the NMS would also result in local device IP address update. This would not be possible without UUIDs, since IP address, that has been changed, is used as the identifying parameter if a UUID is not present.

NMSes that support UUIDs: LibreNMS, NetXMS, Observium and Panopta

Device Action policy

This policy controls the behavior when syncing a device from the NMS. It can be either to always try to Create a new device for the one provided by import source, or try to Move an existing one within a scope, if it is a match.

The default setting is Move within Preset Zones. The "Preset Zones" scope consist of Zones used by Sync Preset's Rules. Before creating a new device (in the target Zone a Rule specifies) the Sync logic will look for an existing device with matching UUID or address within the scope and moves it to the target Zone if one is found. The benefit is keeping track and moving of devices in response to changes in the NMS, which ensures duplicates are not created.

The Move from All Zones option is similar to the previous one, but a system wide scope is used when looking for matching devices to move to the Rule target Zone.

Policy setting No Move/Always Create is used to turn off the moving of devices during the NMS Sync. Only target Zone is looked at when matching a device provided by import source. If a device with the same UUID or address is not present in this Zone, it is created. If it is found, it has its attributes updated. This is handy for environments using same addressing for multiple device in multiple Zones, such as an MSP managing external networks.

Note: moving of existing devices fails if two or more devices with the same identifier are found in the scope, as the algorithm has no way of determining which device the user intended to "move" and counts it as 'failed to update'.

Device Adoption

An adopted device is simply a device that was imported from an NMS by a Sync Preset. Device adoption designates its parent Sync Preset as the only one that manages any changes on it. An existing device in local inventory is eligible for adoption by a Sync Preset when it is not adopted (manually created device) or when it is orphaned. Devices can become orphaned in multiple cases:

• device is no longer present in the device set provided to Unimus by the NMS (was deleted on the NMS, or moved outside the devices Unimus imports)
• when the Zone was changed in a Sync Rule, all devices adopted by this Sync Rule are orphaned
• when the Sync Rule is deleted, all devices adopted by this Sync Rule are orphaned
• when a device is moved to a different Zone manually by the user (this includes the result of Zone deletion with moving of devices to the default Zone)

Orphaning status can be checked via device info.

Adoption is useful for associating not already adopted devices on Unimus with those on the NMS.

Orphaning policy

Orphaning policy determines what happens to orphaned devices during an NMS Sync. User has three options that determine what action to take on orphaned devices during an NMS Sync:

1. No action - device is kept as is, though it is now eligible for adoption by any NMS Sync Preset
2. Unmanage - device becomes unmanaged in Unimus, no further jobs will run on it. It will be kept in Unimus, along with any existing backups; it is also eligible for another adoption
3. Delete - device will be deleted from Unimus, alongside its backups, so this option should be used with a clear intent and a dose of awareness of possible results

Example scenario

Let's simulate a scenario where we want to defer ongoing device management to NMS in a way that any change to device set on NMS is reflected in local inventory on Unimus.

The starting point on Unimus is a set of devices not adopted by any Sync Preset. The first thing that will happen is pairing the devices between the systems and adopting them by our Sync Preset. In addition the devices will also be moved to Zones corresponding with organizational structure present on the NMS. Next, any other devices not present on Unimus will be imported.

This is easily achieved by setting up a Sync Preset with Preset rules specifying organizational groups on the NMS and pointing to specific Zones. Since we want the existing devices moved to specific Zones and we want the algorithm to look for them throughout entire Unimus we will use the 'Move from All Zones' Device Action policy.

After running the NMS Sync we see a successful import notification. Devices are now properly adopted and organized among Zones. Automatic device synchronization is achieved by setting the Sync preset as a 'Scheduled sync'. Any changes, additions or removals of devices in organizational groups on the NMS are reflected in local inventory after the next NMS Sync.

Final words

Congratulations, dear reader, on making it this far! You are now acquainted with the updates to the NMS Sync feature in Unimus. Feel free to experiment with it, and let us know what works and if something doesn't on our Forum.

Intro

With hundreds or even many thousands of jobs daily for some Unimus users, there are bound to be a few failed ones. Jobs such as Discovery or Backup fail for various reasons related to connection errors, refused credentials or unsupported devices. The results of failed jobs are all captured and error logs are viewable in the web GUI. From error logs one can learn the details of why a discovery or a backup for a device failed and use the information to remedy the situation.

In this brief article we will go over generating job report exports. These export files can then be processed externally by a monitoring system, reporting system, by an external parser, or by hand. But first, the error log data needs to be retrieved. The data is stored in the database, so to access it we need the credentials to the database and a few well constructed queries. We will be showing how to generate reports of failed jobs and review them by hand in a spreadsheets editor (Excel) for its advanced data processing functions.

Getting to the data

Unimus supports MySQL, PostgreSQL and MSSQL relational databases in addition to file based HSQL. The former ones store data in tables with columns and rows. Databases use structured query language (SQL) for data manipulation and querying. We'll use such queries to extract the data about failed jobs and export it to a text file.

Connecting to the DB

In our test scenario an arbitrary Unimus server is using MariaDB, a database system, which is a fork of MySQL. For accessing MariaDB we are going to simply run the mariadb client from shell. Need to specify the host IP, database name and credentials:

mariadb --host=127.0.0.1 --database=unimusmdb --user=will -password

Constructing the query

Let's say we are interested in failed Discovery jobs. So for each device we want to get some info about the device itself and error logs for last job that was a failed Discovery.

We will be using data from tables device, device_history_job and zone. The device table contains useful columns like id, address, description, model, type and vendor. The device_history_job table is populated by useful data in the create_time, error_log, info, job_type, device_id and successful columns and the zone table is used to describe device zone membership.

We SELECT columns we want displayed FROM the tables and LEFT JOIN table device_history_job ON id of 'last device job that was a Discovery' via a subquery and table zone ON id of the zone. Then we filter the results with WHERE by 'failed jobs'. And let's say we want to limit the results to recent ones, e.g. ones that took place in the last week. Our query then might look something like this:

SELECT
  d.id,
  dhj.info,
  DATE_FORMAT(FROM_UNIXTIME(dhj.create_time), '%H:%i:%s %d.%m.%Y'),
  z.name,
  dhj.job_type,
  REPLACE(dhj.error_log, '\r\n', ' ') AS error_log
FROM device d
LEFT JOIN device_history_job dhj ON dhj.id = (
  select id
  from device_history_job
  where d.id = device_id
    and job_type = 'DISCOVERY'
  order by create_time
  desc limit 1)
LEFT JOIN zone z ON z.id = d.zone_id
WHERE dhj.successful = 0
  AND dhj.create_time > UNIX_TIMESTAMP(DATE_ADD(CURDATE(), INTERVAL -7 DAY));

We have used REPLACE to output the error log on a single line for a more comprehensible way to display results.

Let's name the columns properly and put the query in quotation marks. Now we can feed the query into the mariadb command via --execute option and write the output into a local file:

mariadb --host=127.0.0.1 --user=will --database=unimusmdb --password --execute="SELECT \
  d.id AS \`ID\`, \
  dhj.info AS \`Device info\`, \
  DATE_FORMAT(FROM_UNIXTIME(dhj.create_time), '%H:%i:%s %d.%m.%Y') AS \`Time\`, \
  z.name AS Zone, \
  dhj.job_type AS \`Job type\`, \
  REPLACE(dhj.error_log, '\r\n', ' ') AS \`Error log\` \
FROM device d \
LEFT JOIN device_history_job dhj ON dhj.id = (\
  select id \
  from device_history_job \
  where d.id = device_id \
    and job_type = 'DISCOVERY' \
  order by create_time \
  desc limit 1) \
LEFT JOIN zone z ON z.id = d.zone_id \
WHERE dhj.successful = 0 \
  AND dhj.create_time > UNIX_TIMESTAMP(DATE_ADD(CURDATE(),INTERVAL -7 DAY))" > disco_local.csv

For failed Backup jobs we would just change the job_type in the WHERE section of the query to 'BACKUP'. Also, since a successful Discovery is a prerequisite for a Backup job, we can select additional columns, like vendor, type and model, to describe the discovered device in more detail. Queries and shell commands for failed backups, along with Postgres and MSSQL versions can be found on our GitHub.

Reviewing the data

We are using OnlyOffice Excel in our scenario because it is free and gets the job done. To view the data simply open the file in your favorite spreadsheets tool and choose 'Tab' as the delimiter:

Alternatively you can import the data using the Data Import feature:

Now select the data and format it as a table for advanced filtering capabilities. You can then filter the results by devices, zones or specific keywords in the error log messages. Here is an example of how to filter the logs based on multiple criteria:

Conclusion

And that's basically it! This short guide should provide a starting point for generating and viewing failed job reports from Unimus. There is also a thread going on our Forum for any feedback, questions or possible improvements.

The purpose of this article is to guide you through configuration for running Unimus remote Core container image on MikroTik's RouterOS.

Introduction

Today we will be discussing an exciting feature of Unimus - support for remote networks and distributed polling. Managed devices do not always have to be directly reachable by the Unimus Server. In a scenario where our devices and Unimus are separated by a WAN it would make sense to utilize a remote agent. All client devices would be polled locally which eliminates the need for individual direct server-device connections. This saves resources such as bandwidth and processing power and simplifies administration as you only need to maintain connectivity to a single host in each remote location. We would also get vastly improved scalability, enhanced security and fault isolation.

Getting to the Core™ of the matter

To extend Unimus functionality to a remote network we would use Unimus Core. A Core is the brains of Unimus. Same as the embedded Core on any Unimus Server it performs network automation, backups, change management and more on managed network devices. Acting as a remote poller, Unimus Core communicates with Unimus Server over a secure TCP connection conforming to modern industry standards. We can install Unimus Core on any supported OS, run a portable version or run a container image. Find out more on our wiki.

Fairly recently (August 2022) MikroTik added container support on their RouterOS. This introduces a nifty new way of deploying Unimus Core directly on an edge router, thus reducing the number of devices required in the network. Let's have a look at how to set this up.

Setup

Behold, the system we will be testing our remote Core deployment on:

Starting from the right, the Unimus Server is installed on Ubuntu server (22.04) running on Raspberry Pi 2. It is connected via static IP to the HQ router – a MikroTik RouterBOARD. The HQ router is doing source NAT for Unimus Server, translating the private source IP to WAN interface public IP. This allows Unimus Server to reach resources outside the LAN.

HQ router is also configured for destination NAT, a.k.a port triggering, directing incoming TCP 5509 and TCP 8085 traffic to Unimus Server. TCP 5509 allows inbound remote Core connection. TCP 8085 is not strictly required for our demonstration, we open it simply for remote access to the HTTP GUI.

The left side represents a remote network. Branch router, a MikroTik RB5009UG+S+, is our edge router capable of running containers. Connected on LAN side is the device we want to manage, another MikroTik RouterBOARD - Branch switch. Branch router supports containers and will run Unimus Core in one.

Our Unimus Core container will have its own virtual ethernet interface assigned to use for communication outside. Although this 'veth' could be added to the local bridge connecting to Branch switch, it makes more sense security-wise to add it to a separate 'containers' bridge. This way any container traffic goes through the routing engine and firewall, where it can be subject to policies.

Branch router, which is likely source NATting traffic for the whole branch network, needs to also SNAT the container subnet to allow outbound communication to the Unimus Server.

Edge router WAN ports are reachable via internet simulated by a local network. This is sufficient for our testing purposes as it simulates indirect connectivity between the Unimus Server and the remote Core.

With all the moving (really just sitting and humming softly) parts introduced, let’s go through the steps needed to achieve our desired result in detail.

Configuration

The key parts we will be focusing on are Unimus Server and MikroTik RouterBOARD (Branch router) running Unimus Core in a container.

Unimus Server

We assume we already have Unimus Server up and running. If not feel free to check out our wiki to get you started.

Once we are all set, we can begin by navigating to Zones and 'Add new Zone'. This Zone will represent our remote location. Enter Zone name, ID and Remote core connection method and hit 'Confirm' to proceed.

Next, we retrieve the remote core access key by hitting 'Show' and save it for later. It will be used to establish connection to the Unimus Server.

Branch router and Unimus Core

Before attempting to run any containers let's take care of the prerequisites:

RouterOS version 7.5 or higher is needed to run containers so update as necessary. Container package is compatible with arm, arm64 and x86 architectures.

Requirements above are met. We have that going for us which is nice. The following steps will get us through the process of configuring the Branch router:

secure the router as it is dangerous on the internet

Take care of basic security. Configure a strong password and restrict management access using a firewall policy.

get the container package and install it

Visit mikrotik.com/download and get the 'extra packages' for your architecture. Extract the contents, upload the containers package to your router and reboot.

After reboot we can verify the currently installed packages:

enable device-mode containers

We need to have physical access to the router for this part due to security implications. We'll be prompted to press the reset button to apply the setting.

/system/device-mode/update container=yes

configure container interface

To allow our container access to the network it needs a virtual interface. First we will create a bridge for the container:

/interface/bridge/add name=containers
/ip/address/add address=10.1.1.1/24 interface=containers

Then we'll create a veth1 interface and assign an IP address that Unimus Core will use for communication to Unimus Server. And we add the interface to the newly created bridge:

/interface/veth/add name=veth1 address=10.1.1.2/24 gateway=10.1.1.1
/interface/bridge/port add bridge=containers interface=veth1

configure NAT

Source NAT is needed for communication outside. We want the connection originated from the container subnet translated to an IP address reachable from the outside:

/ip/firewall/nat/
add action=masquerade chain=srcnat src-address=10.1.1.0/24 out-interface=ether1

use an external drive (optional)

To avoid cluttering your platform storage we recommend using a usb stick or an external hard drive for container images and volumes. They need to be formatted to ext3 or ext4 filesystem:

Onto the configuration of the container for Unimus Core. We need to specify where to reach the Unimus Server via container environment variables, pull the Unimus Core container image and run it.

define environment variables

Variables are defined in key-value pairs. These are needed to point Unimus Core to the Unimus Server and input the Access Token we got earlier. Additionally, we can set the timezone and memory constraints for Java and there is an option to define volumes' mount points for data persistence. Details on GitHub.

/container/envs/

add key=UNIMUS_SERVER_ADDRESS name=unimuscore_envs value=10.2.3.4
add key=UNIMUS_SERVER_PORT name=unimuscore_envs value=5509
add key=UNIMUS_SERVER_ACCESS_KEY name=unimuscore_envs value=\
    "v3ry_crypto;much_s3cr3t;W0w.."
add key=TZ name=unimuscore_envs value=Europe/Budapest
add key=XMX name=unimuscore_envs value=256M
add key=XMS name=unimuscore_envs value=128M

/container/mounts/

add dst=/etc/unimus-core name=unimuscore_config src=/usb1-part1/config

adding container image

We will be pulling our Unimus Core container latest image straight from Docker hub at https://registry-1.docker.io. You could also import one from a PC (via docker pull/save) or build your own. The remote Core needs to be the same version as the embedded core on Unimus Server to avoid any compatibility issues between versions. So just make sure you grab a suitable version.

/container/config/set
registry-url=https://registry-1.docker.io tmpdir=usb1-part1/pull
/container/add
remote-image=croc/unimus-core-arm64:latest interface=veth1 root-dir=usb1-part1/unimuscore mounts=unimuscore_config envlist=unimuscore_envs logging=yes

- tmpdir specifies where to save the image
- root-dir specifies where to extract the image
- mounts specify mount points for volumes to ensure data persistence if container is removed or replaced
- envlist specifies environment variables defined above
- logging is enabled for troubleshooting

After extraction it should go to "stopped" status. Check via:

/container/print

run it!

All is set to start our remote Unimus Core.

/container/start 0

run on boot (optional)

It might come in handy configuring our container to start with RouterOS boot to add some automation in case the Branch router gets rebooted for any reason.

/container/set start-on-boot=yes 0

All is well that ends well

Assuming we have set it all up and everything went as planned we should see our remote Core’s status as online:

Adding our test device (the Branch Switch) under remote Core zone (BO1) prompts a discovery which results in success:

Troubleshooting

Most common issues relate to Unimus Server connectivity. Here’s a checklist of items we can try in case of need:

• Unimus Server is UP

Double-check your Unimus Server is up and running. Access it via browser at http(s)://<YourServerIP:8085/

• Firewall policy

Verify whether there’s a security rule allowing connection from outside your network.

• Check NAT

Destination NAT rule is necessary for core connection traffic. We need to translate destination address of incoming remote Core traffic to the Unimus Server IP address. TCP port 5509 is used by default.

• Check variables

Our Unimus Core container uses environment variables to establish connection to the server. Make sure the values in key-value pairs reflect your setup:

UNIMUS_SERVER_ADDRESS is the IP address where Unimus Server is reachable (before NAT)

UNIMUS_SERVER_PORT is the TCP port number (default 5509) on which Unimus listens for remote core messages

UNIMUS_SERVER_ACCESS_KEY is the long string generated when you create a new Remote Core Zone

Enabled container logs make troubleshooting easier:

• Check versions

For Unimus Server to accept the remote Core connection they both need to run on the same version. Unimus Server log file would reveal this issue:

Attached below are the config exports used in our test setup:

# HQ router
/interface bridge
add name=local
/interface bridge port
add bridge=local interface=ether2
/ip address
add address=172.31.254.1/24 interface=local network=172.31.254.0
add address=10.2.3.4/24 comment=internet interface=ether1 network=10.2.3.0
/ip dhcp-server network
add address=172.31.254.0/24 dns-server=172.31.254.1 gateway=172.31.254.1
/ip dns
set servers=10.2.3.254 allow-remote-requests=yes
/ip firewall nat
add action=masquerade chain=srcnat out-interface=ether1
add action=dst-nat chain=dstnat dst-address=10.2.3.4 dst-port=5509,8085 protocol=tcp to-addresses=172.31.254.2
/ip route
add distance=1 gateway=10.2.3.254
/system clock
set time-zone-name=Europe/Bratislava
/system identity
set name=HQ

# Branch router
/interface bridge
add name=containers
add name=local
/interface veth
add address=10.1.1.2/24 gateway=10.1.1.1 name=veth1
/container mounts
add dst=/etc/unimus-core name=unimuscore_config src=/usb1-part1/config
/container
add envlist=unimuscore_envs interface=veth1 logging=yes
/container config
set registry-url=https://registry-1.docker.io tmpdir=usb1-part1/pull
/container envs
add key=UNIMUS_SERVER_ADDRESS name=unimuscore_envs value=10.2.3.4
add key=UNIMUS_SERVER_PORT name=unimuscore_envs value=5509
add key=UNIMUS_SERVER_ACCESS_KEY name=unimuscore_envs value="secret key"
add key=TZ name=unimuscore_envs value=Europe/Budapest
add key=XMX name=unimuscore_envs value=256M
add key=XMS name=unimuscore_envs value=128M
/interface bridge port
add bridge=local interface=ether2
add bridge=containers interface=veth1
/ip address
add address=10.8.9.10/24 interface=local network=10.8.9.0
add address=10.5.6.7/24 comment="internet" interface=ether1 network=10.5.6.0
add address=10.1.1.1/24 interface=containers network=10.1.1.0
/ip dns
set servers=10.5.6.254  allow-remote-requests=yes
/ip firewall nat
add action=masquerade chain=srcnat src-address=10.1.1.0/24 out-interface=ether1
/ip route
add disabled=no dst-address=0.0.0.0/0 gateway=10.5.6.254 routing-table=main
/system clock
set time-zone-name=Europe/Bratislava
/system identity
set name="Branch router"

Final words

We hope this guide can serve as a template for deploying Unimus Core container on MikroTik’s RouterOS. If you encounter any difficulties or have additional questions please reach out on the forum.

Today we will have a look at how you can handle devices which don't output their configs over CLI, which is not supported by Unimus out-of-the-box. However, a bit of scripting and Unimus' API enables you to navigate around this adversity.

Intro

Configuration backup is an essential practice in any network environment. Possessing recent configuration files safeguards against data loss or system failure and lets you restore your network to a working state much faster than redeploying everything manually from scratch. Believe me this has saved money (and people's jobs) in the past.

Back on a serious note, as a full-featured Network Configuration Management solution Unimus performs these backup duties for you. Over time, Unimus also builds a versioned configuration history of your network from each device backup and notifies you of any and all changes in your network. With this superior visibility Unimus gives you a whole new level of change management adding on to other user favorite features like configuration auditing and change automation.

How Unimus backs up your devices and when devices make it complicated

Unimus gathers backups from managed devices via CLI as any user would. It logs into the device using Telnet or SSH (please don't use Telnet however) and then retrieves the configuration of the device. And therein lies a potential issue. Not all systems have a CLI, such as MikroTik's SwOS (learn how you can get around it in this article on our blog), and some that have a CLI do not support CLI-based configuration backup. We'll call these the Unbackupables.

To illustrate an example, let's have a look at FortiAuthenticator by FortiNet. As a network element which provides centralized authentication services its configuration consists of both a textual configuration, available over the CLI, and a configuration database, which is managed through a web GUI. The config DB includes users, groups, the FortiToken device list, certificates, and many other config elements. All of them can be neatly packed into a binary backup file. FortiAuthenticator allows you to set up auto-backup. This is done by specifying an FTP server address, FTP directory, backup frequency and backup time.

Another example where CLI doesn't support a config dump is PMP 450 access points by Cambium. Complete configuration can be downloaded via web interface and it will be stored in a text file (.cfg). The backup file can then be passed along to an FTP server using device specific CLI commands.

We now have knowledge about particularities of backups in some devices and, as was cleverly foreshadowed above, we can have binary/text backup files pushed to an FTP server (TFTP, SCP or SFTP also works). We can also push backups into Unimus using its API. Let's use all this and a few lines of code to backup even the Unbackupable.

Setup

In real-world deployments, topologies can and will be complex. However with our setup it all boils down to three discrete components - the network device, an FTP server and Unimus, plus a script to tie it all together. Then we automate the process via scheduling. The following section captures our test environment in more detail:

1) A cisco router on the left, will represent our Unbackupable - a network device Unimus cannot directly pull a config backup from. It needs to have the backup delivered to an FTP server. Just a note - we are using a Cisco device just for illustration as Unimus supports all Cisco devices natively, without needing to use an FTP server.

2) An FTP (or TFTP, SCP, SFTP...) server runs on either Linux or Windows Server. The only difference being what script version we use - Shell or Powershell. The script will push backups to Unimus (using the API) from files on the FTP server.

3) Unimus. We assume you already have your Unimus server up and running. If not, we have a guide for how to deploy Unimus on our wiki.

The Script. Simply put, it creates backups on Unimus via API. It is described in detail later.

For our setup to work, device backups need to somehow find themselves on the FTP server. There are two scenarios how this can be achieved:

1) Device itself is capable of a scheduled backup push to an FTP server

Similar to the FortiAuthenticator example, mentioned in the Intro, a device can be set up to push its config backup to an FTP server. Likewise, on Cisco IOS, Embedded Event Manager (EEM) feature enables you to create EEM Applet to execute action "copy config to FTP" when event "scheduled time" is triggered. The following image illustrates this logic:

This is the simpler scenario. Only two jobs need to be scheduled. First one on Cisco router via EEM applet that pushes running configuration to an FTP server at a scheduled time. Example below:

event manager applet backup-config-daily
 event timer cron name daily-time cron-entry "30 3 * * *"
 action 1.0 cli command "enable"
 action 2.0 cli command "copy running-config ftp://username:password@ftp-server-ip/router.ip.address/config-$(date \"+%Y%m%d%H%M%S\").cfg"

Second job is scheduled on the host running FTP server via Cron or Task Scheduler, depending on the environment used.

2) The other option - device has to be periodically instructed to push its backup to an FTP server

Since the device itself is incapable of automatically backing itself up to the FTP server, an outside agent (Unimus) will send commands to the device instructing it to create a config backup and copy it to an FTP server according to a schedule.

Although this diagram looks more complicated, again, we only need to schedule two jobs. First one runs on Unimus. It is a Mass Config Push preset following a daily schedule:

tclsh
regexp {\S+ +\S+ +(\w+) +(\d+) +(\d+)} [exec show clock] match month day year
exec copy run ftp://my.ftp.server/router.ip.address/config-$day-$month-$year

In both scenarios the second job is the execution of script on host running FTP server that pushes backups to Unimus. We will schedule it in Cron or Task Scheduler, depending on the environment.

Pushing the backups from the FTP server to Unimus

Once config backups are copied to the FTP server, be it in binary or text form, our script can push them to Unimus. Backups of the devices will be stored on the FTP server following this specific structure for convenience:

Each device has a separate directory using its management IP address as name, where all configuration backup versions are stored:

On the host with the FTP server we will be running a script (Linux shell or Powershell) that uploads the config backups to Unimus. Here are the steps it takes:

1. Comb through each subdirectory under defined root directory extracting the directory name (in form of IP address)
2. Look up device on Unimus; (optional) work on specified Zone; (also optional) create a new device if none is found
3. Encode each backup file found in a subdirectory to base64 string digestible by Unimus
4. Create device backup on Unimus via API from oldest to newest and delete it from ftp directory

Shell script

The full ready-to-use script can be found on our GitHub. If you are using the Powershell script, just skip to the Powershell section. We will focus on the Bash script in this section.

You can just download and use it. If you are curious in its internal functioning, feel free to read on!

Working mainly with APIs we will be using curl and jq packages. Install as necessary.

To start let's define mandatory variables for convenient parametric approach. This is the only part of the script we need to adjust for our environment to make it work. Apart from Unimus hostname/IP address, generated API token and http headers the script only needs to know the FTP root directory where the configs are saved.

# Mandatory parameters
UNIMUS_ADDRESS="<http(s)://unimus.server.address(:port)>"
TOKEN="<api token>"
# FTP root directory
FTP_FOLDER="/home/user/ftp_data/"

Next there are some optional parameters that are enabled by uncommenting the variables. From Unimus version 2.4.0-Beta3 we can specify a Zone for the script to work on. We can enable curl insecure option if self-signed certificate is used. Also we have an option to create new devices in Unimus if specific ones have not yet been added.

# Optional parameters
# Specifies the Zone where devices will be searched for by address/hostname
# CASE SENSITIVE; leave commented to use the Default (0) zone
#ZONE="0"
# Insecure mode
# If you are using self-signed certificates you might want to set this to true
SELF_SIGNED_CERT=false
# Variable for enabling creation of new devices in Unimus; set to true to enable
CREATE_DEVICES=false
# Specify description of new devices created in Unimus by the script
CREATED_DESC="The Unbackupable"

Our backup solution is based on API calls to Unimus. Create new device and Get device by address are APIs from APIv2. Both functions createNewDevice and getDeviceId require device IP address as input ($1). GetDeviceId returns device ID value from the response using | jq .data.id. When working with a specific Zone, createNewDevice sends an additional key-value pair in the body and getDeviceId appends zoneId parameter to the URI. Check out the full API documentation on wiki.

function createNewDevice() {
    if [ -z "$ZONE" ]; then
        curl $insecure -X POST -sSL -H "$HEADERS_ACCEPT" -H "$HEADERS_CONTENT_TYPE" -H "$HEADERS_AUTHORIZATION" -d '{"address": "'"$1"'","description":"'"$CREATED_DESC"'"}'\
        "$UNIMUS_ADDRESS/api/v2/devices" > /dev/null
    else
        curl $insecure -X POST -sSL -H "$HEADERS_ACCEPT" -H "$HEADERS_CONTENT_TYPE" -H "$HEADERS_AUTHORIZATION" -d '{"address": "'"$1"'","description":"'"$CREATED_DESC"'", "zoneId": "'"$ZONE"'"}'\
        "$UNIMUS_ADDRESS/api/v2/devices" > /dev/null
    fi
}

function getDeviceId() {
    if [ -z "$ZONE" ]; then
        echo "$(curl $insecure -X GET -sSL -H "$HEADERS_ACCEPT" -H "$HEADERS_AUTHORIZATION" "$UNIMUS_ADDRESS/api/v2/devices/findByAddress/$1" | jq .data.id)"
    else
        echo "$(curl $insecure -X GET -sSL -H "$HEADERS_ACCEPT" -H "$HEADERS_AUTHORIZATION" "$UNIMUS_ADDRESS/api/v2/devices/findByAddress/$1?zoneId=$ZONE" | jq .data.id)"
    fi
}

Create new backup API call is done by the createBackup function. It needs device ID ($1) and a JSON ($2) with base64 string of backup file and TEXT/BINARY string as input arguments.

function createBackup() {
    curl $insecure -X POST -sSL -H "$HEADERS_ACCEPT" -H "$HEADERS_CONTENT_TYPE" -H "$HEADERS_AUTHORIZATION" -d "@$2" "$UNIMUS_ADDRESS/api/v2/devices/$1/backups" > /dev/null
}

The functions above will be used in the main function - processFiles.

processFiles function does the following:

• finds sub-directories inside provided ftp folder
• retrieves device ID, creates new device in Unimus if none is found
• sorts files inside each sub-directory by modification date from oldest to newest
• converts each file to base64 string
• checks if file is binary or text, creates binary/text backup accordingly and deletes the file

function processFiles() {
    # Set script directory for the script
    script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" &>/dev/null && pwd -P)
    cd $script_dir

    # Creating a log file
    log="$script_dir/unbackupables.log"
    printf 'Log File - ' >> $log
    date +"%F %H:%M:%S" >> $log

    # Insecure curl switch
    if $SELF_SIGNED_CERT; then
        insecure="-k"
    fi

    # Perform Unimus health check
    status=$(healthCheck)
    errorCheck "$?" 'Status check failed'

    if [ $status == 'OK' ]; then
        [ -n "$ZONE" ] && zoneCheck
        echoGreen 'Checks OK. Script starting...'
        ftp_directory="$1"
        # Begin sweeping through the specified FTP directory
        for subdir in "$ftp_directory"/*; do
            if [ -d "$subdir" ]; then
                # Interpret directory names as device addresses/host names in Unimus
                address=$(basename "$subdir")
                # Check if device already exists in Unimus
                id=$(getDeviceId "$address")
                if [ $id = "null" ]; then
                    if $CREATE_DEVICES; then
                        createNewDevice "$address" && id=$(getDeviceId "$address") && echoGreen "New device added. Address: $address, id: $id"
                    fi
                fi
                if [ $id = "null" ] || [ -z "$id" ]; then
                    echoYellow "Device $address not found on Unimus. Consider enabling creating devices. Continuing with next device."
                else
                    for file in $(ls -t "$subdir"); do
                        if [ -f "$subdir/$file" ]; then
                            isTextFile=$(file -b "$subdir/$file")
                            if [[ $isTextFile == *"text"* ]]; then
                                bkp_type="TEXT"
                            else
                                bkp_type="BINARY"
                            fi
                            encoded_backup=$(base64 -w 0 "$subdir/$file")
                            temp_json_file=$(mktemp)

                            cat <<-EOF > "$temp_json_file"
                            {
                            "backup": "$encoded_backup",
                            "type": "$bkp_type"
                            }
EOF
                            # Use jq to process the JSON from the temporary file
                            jq '.' "$temp_json_file" > output.json
                            createBackup "$id" "output.json" && echoGreen "Pushed $bkp_type backup for device $address from file $file"
                            # Clean up the temporary files & backup file
                            rm "$temp_json_file" output.json "$subdir/$file"
                        fi
                    done
                fi
            fi
        done
    else
        if [ -z $status ]; then
            echoRed 'Unable to connect to unimus server'
            exit 2
        else
            echoRed "Unimus server status: $status"
        fi
    fi
    echoGreen 'Script finished'
}

Function is called supplying ftp root folder defined in the beginning:

processFiles $FTP_FOLDER

As we mentioned earlier, you can get the script in its wholesomeness on GitHub.

Powershell script

Corresponding code walkthrough for Windows environments using Powershell can be found in this section. Grab the complete script from GitHub or continue perusing if you're interested in how it works under the hood!

The only part that we need to update for a specific setup is the mandatory variables. Required are Unimus hostname/IP address, API token generated in Unimus and the location of FTP root directory.

# Mandatory parameters
$UNIMUS_ADDRESS = "<http(s)://unimus.server.address(:port)>"
$TOKEN = "<api token>"
# FTP root directory
$FTP_FOLDER = "/ftp_data"

Optionally we can specify the Zone we want to work on. This works from 2.4.0-Beta3. Next we can enable skipping certification check for when you are using self-signed certificate on Unimus. The script handles this in a separate fashion based on the version of Powershell present on the system. Also, variable $CREATE_DEVICES controls adding devices to Unimus if they're not present already.

# Optional parameters
# Specifies the Zone where devices will be searched for by address/hostname
# CASE SENSITIVE; leave commented to use the Default (0) zone
#$ZONE="0"
# Insecure mode
# If you are using self-signed certificates you might want to set this to true
$INSECURE = $false
# Variable for enabling creation of new devices in Unimus; set to true to enable
$CREATE_DEVICES = $false
# Specify description of new devices created in Unimus by the script
$CREATED_DESC = "Unbackupable"

Create new device and Get device by address API endpoints are accessed using functions Create-NewDevice and Get-DeviceId. Device IP address ($address) is used as a parameter for both functions. Get-DeviceId returns .data.id value (device ID) from API response. Get-DeviceId is also handling response exceptions by returning null when a device doesn't exist on Unimus. When working on non-default Zone Create-NewDevice adds zoneId key-value pair to its data payload and Get-DeviceId appends zoneId to the URI. Full API documentation can be found on wiki.

function Create-NewDevice {
    param(
        [string]$address
    )

    $body = @{
        address = $address
        description = $CREATED_DESC
    }

    if ($ZONE) {
        $body["zoneId"] = $ZONE
    }

    $body = $body | ConvertTo-Json

    $headers = @{
        "Accept" = "application/json"
        "Content-Type" = "application/json"
        "Authorization" = "Bearer $TOKEN"
    }

    if ($INSECURE -and $psMajorVersion -ge 6) {
        Invoke-RestMethod -SkipCertificateCheck -Uri "$UNIMUS_ADDRESS/api/v2/devices" -Method POST -Headers $headers -Body $body | Out-Null
    } else {
        Invoke-RestMethod -Uri "$UNIMUS_ADDRESS/api/v2/devices" -Method POST -Headers $headers -Body $body | Out-Null
    }
}

function Get-DeviceId {
    param(
        [string]$address
    )

    $headers = @{
        "Accept" = "application/json"
        "Authorization" = "Bearer $TOKEN"
    }

    if ($ZONE) {
        $uri="api/v2/devices/findByAddress/" + $address + "?zoneId=" + $ZONE
    } else {
        $uri="api/v2/devices/findByAddress/" + $address
    }

    try {
        if ($INSECURE -and $psMajorVersion -ge 6) {
            $response = Invoke-RestMethod -SkipCertificateCheck -Uri "$UNIMUS_ADDRESS/$uri" -Method GET -Headers $headers
        } else {
            $response = Invoke-RestMethod -Uri "$UNIMUS_ADDRESS/$uri" -Method GET -Headers $headers
        }
        return $response.data.id
    }
    catch {
        if ($_.Exception.Response.StatusCode -eq 404) {
            return "null"
        }
    }
}

Create new backup API is called through Create-Backup function. It is using device ID($id), base64 string of the backup file ($encodedBackup) and TEXT/BINARY ($type) as input.

function Create-Backup {
    param(
        [string]$id,
        [string]$encodedBackup,
        [string]$type
    )

    $body = @{
        backup = $encodedBackup
        type = $type
    } | ConvertTo-Json

    $headers = @{
        "Accept" = "application/json"
        "Content-Type" = "application/json"
        "Authorization" = "Bearer $TOKEN"
    }
    if ($INSECURE -and $psMajorVersion -ge 6) {
        Invoke-RestMethod -SkipCertificateCheck -Uri "$UNIMUS_ADDRESS/api/v2/devices/$id/backups" -Method POST -Headers $headers -Body $body | Out-Null
    } else {
        Invoke-RestMethod -Uri "$UNIMUS_ADDRESS/api/v2/devices/$id/backups" -Method POST -Headers $headers -Body $body | Out-Null
    }
}

The main function Process-Files executes the following logic:

• finds subdirectories inside provided ftp folder
• retrieves device ID, creates new device in Unimus if none is found
• sorts files inside each subdirectory by modification date from oldest to newest
• converts each file to base64 string
• checks if file is binary or text, creates binary/text backup accordingly and deletes the file

function Process-Files {
    param(
        [string]$directory
    )

    $log = Join-Path $PSScriptRoot "unbackupablesPS.log"
    $logMessage = "Log File - " + (Get-Date -Format "yyyy-MM-dd HH:mm:ss")
    Add-Content -Path $log -Value $logMessage
    #Health check
    $status = Health-Check

    if ($status -eq 'OK') {
        if ($ZONE) {
            Zone-Check
        }

        Print-Green "Checks OK. Script starting..."
        $ftpSubdirs = Get-ChildItem -Path $directory -Directory

        foreach ($subdir in $ftpSubdirs) {
            $address = $subdir.Name
            # Check if device already exists in Unimus
            $id = "null"; $id = Get-DeviceId $address

            if ($id -eq "null" -and $CREATE_DEVICES) {
                Create-NewDevice $address
                $id = Get-DeviceId $address
                Print-Green ("New device added. Address: " + $address + ", id: " + $id)
            }

            if ($id -eq "null" -or $id -eq $null) {
                Print-Yellow ("Device " + $address + " not found on Unimus. Consider enabling creating devices. Continuing with next device.")
            } else {
                $files = Get-ChildItem -Path $subdir.FullName | Sort-Object -Property LastWriteTime -Descending

                foreach ($file in $files) {
                    if ($file.GetType() -eq [System.IO.FileInfo]) {
                        $content = [System.IO.File]::ReadAllBytes($file.Fullname)
                        $encodedBackup = [System.Convert]::ToBase64String($content)

                        if ($content -contains 0) {
                            $bkp_type = "BINARY"
                        } else {
                            $bkp_type = "TEXT"
                        }
                        Create-Backup $id $encodedBackup $bkp_type
                        Print-Green ("Pushed " + $bkp_type + " backup for device " + $address + " from file " + $($file.Name))
                        Remove-Item $file.FullName
                    }
                }
            }
        }
    } else {
        Print-Red "Unimus server status: $status"
    }
    Print-Green "Script finished."
}

To run, call the main function via:

Process-Files -directory $FTPFOLDER

That's all she wrote! Here's a GitHub link with the full version of the script.

Scheduling with Cron

This section takes care of the automation part of the whole config push process. On Linux we can run our script at a predefined time using Cron. Add user-specific job via crontab -e and insert the following line:

0 4 * * * /path/to/your_Unbackupables_script.sh

Task Scheduler

All you gamer folk working in Windows Server environment can use Task Scheduler to run the Powershell version of the script. These are the steps needed:

1) Under Actions hit 'Create task' and provide a name and description.

2) Switch to Triggers tab, create a 'New' trigger and specify the start time and frequency of your choice.

3) In Actions tab hit 'New'. Select 'Start a program' as action, browse for PowerShell executable and add an argument by supplying the path to the Powershell script.

After confirming we can see our new task 'push backups to Unimus' in Task Scheduler Library. It is now ready to automatically run according to our specified schedule.

Backup push aftermath in Unimus

After the script runs we should see new backups created in Unimus:

Note that new device backups may show almost identical timestamps. This could happen when the script makes multiple API calls due to a collection of config files accumulated inside a single device folder on the FTP server. Likely scenario is an initial script execution when we start with a considerable backup history that we want pushed to Unimus from FTP. Or when the script is not executed periodically and configs on FTP stack up. If your backup push script runs with (slightly after) your 'copy backup to FTP' schedule, this should not happen. Even if it does the backups on Unimus would be created with preserved chronology thanks to the script's internal logic.

T-shooting

Things sometimes work out on the first try. More often tho, they don't. If your case is "they don't", keep on reading.

There are a few possible sources of headache - FTP directory structure, Unimus API, working Zone selection and using self-signed certificate being the likely candidates. Let's have a closer look at each.

Directory structure nerve wreckers

Successful implementation of the backup handling in our scripts heavily relies on directory structure of your FTP server. Or on how robust the script is (we did our best). In our setup each managed device has its own folder named after device IP address or host name. Each folder in turn contains backup file versions for a given device. Make sure your setup keeps this structure.

API mishaps

There should not be any but if issues with API calls arise one can check the following.

Every API request includes Authorization header that supplies 'API token', in order to authorize the request, following this scheme:

Authorization: Bearer <token>

To create a token log in to your Unimus instance and navigate to User management > API tokens. Make sure you copy the whole string to the mandatory variable 'TOKEN' value. Otherwise you might get the following error:

ERROR: Unimus server status: null

Zone related blunders

The script is designed to push backups to a specific Zone in Unimus, default one if no Zone is specified. If the specified Zone does not exist you will get an error:

ERROR: Error. Zone <ZoneID> not found!

Just make sure to specify an existing Zone ID. Zone ID is case sensitive.

Self-signed cert predicaments

If you encounter errors with the script it pays to double-check optional parameters. Self-signed certificate on Unimus might give you SSL related errors if issued by a certificate authority unknown/untrusted to the system you're executing the script from. Enabling 'certification check skip' in the script is an option to consider.

Final words

We hope you will find this tutorial helpful for integrating configuration backups to Unimus from devices that do not support backups from CLI. We appreciate any feedback, questions or possible improvements and have a thread on our Forum for just that purpose.

In this guide, we would like to show you how to pair your Active Directory with Unimus and use LDAP for the AAA.

We will be focusing on AD running on Windows Server, and we will assume you have your server already set up with Active Directory.

Preparing for LDAP - Organizational structure in Active Directory

As LDAP is integrated and available in Active Directory by default, let's start by briefly showcasing the simple, exemplary organizational structure we created in Active Directory Users and Computers:

We created a simple structure of a couple of child Organizational Units (OUs) under the unimus.local domain, more specifically unimus.local > Unimus > Unimus Admins.

Let's take another look at them in the ADSI Edit utility, where we can have a better view of their Distinguished Names (DNs):

ADSI Edit gives us a more useful (for us in this context) view of our organizational structure. We can see how each object chains and contributes to the DN of our target OU Unimus Admins.

OU=Unimus Admins,OU=Unimus,DC=unimus,DC=local

This DN will serve as a Base DN in Unimus for the lookup of the objects (users) based on an User Identifier attribute we will choose. As per Unimus' LDAP documentation (more on this later), we need to specify a Base DN which will serve as the root point for Unimus to search users from.

The last thing to look at is one of our users. Let's pick Jane Doe as an example and see how this user's DN looks:

CN=Jane Doe,OU=Unimus Admins,OU=Unimus,DC=unimus,DC=local

This is Jane Doe's DN; however, we don't have to use this full DN to identify Jane Doe. We can choose whichever of the available attributes of this account to use - assuming these attributes exist and do not have blank values. By right-clicking Jane Doe's record and choosing Properties, we can see the Attribute Editor, where we can examine and edit existing attributes or add new values to other unused attributes:

In this view, we can sort values so that we see all non-blank attributes together. In typical Windows AD deployments, you usually use the sAMAccountName attribute to lookup AD users instead of the DN. This is typically the username for Windows AD logins, so we will use this for the configuration in Unimus as well.

LDAP integration in Unimus

Before we jump into the configuration section, let's start with some details on how LDAP auth works in Unimus. The process of authenticating a local user in Unimus against an external LDAP is done in two stages.

1) In the first stage, the Unimus LDAP client logs into the LDAP directory using the provided server details and accesses user credentials (DN and password). If the login is successful, Unimus will search for the provided user (the user attempting to log into Unimus) in the target directory tree defined by a base DN. If the user is matched using any configurable attribute (the User Identifier), Unimus proceeds to the second stage.

2) In the second stage, Unimus uses the previously matched provided username to retrieve the full user DN and attempts to authenticate the user with the provided password. If the authentication succeeds, the user is logged into Unimus.

For more details about authentication, security options, and OpenLDAP / AD configuration examples, we recommend taking a minute to check out our Wiki article, which goes over all of the above and more: https://wiki.unimus.net/display/UNPUB/LDAP+Auth

The LDAP Access User

As mentioned above, we need an Access User which will be used to find the exact account trying to log in to Unimus. The Access User can be any LDAP account that has access (read-only access is sufficient) to the LDAP tree under which your login users exist. More info in the Wiki articled mentioned above.

The Access User of course also needs to be able to "see" the user account objects as well, not just the OUs in your directory.

Unimus configuration - Configuring LDAP

You can configure LDAP in User management > LDAP configuration:

Where:

LDAP server address - the address of your domain controller.

LDAP port - the default port is 389.

LDAP access user DN - full DN of the user able to access AD records.

LDAP access password - a password for the access user.

Security - an optional security measure for LDAP transmission. Both LDAPS and StartTLS require respective server-side (the LDAP server) configurations.

Note, if you opt to use LDAPS or StartTLS including certificate validation, you can follow our guide on importing CA certificates in Unimus; both require importing your CA to the system's Java KeyStore. You don't need to do this if you enable Do not check certificate to skip LDAP cert validation.

LDAP base DN - the DN of the root of the tree storing user records, which Unimus will be authenticating login attempts against.

User identifier - an identifier that Unimus uses to match users in LDAP to retrieve user's full DN for auth purposes. You can use any attribute that suits your needs. For example, you can use CN, sAMAccountName, uid, etc.

LDAP filter - an optional LDAP filter to further filter matches in the given base DN. Standard LDAP filter syntax is supported.

Unimus configuration - Adding LDAP accounts to Unimus

Unimus currently requires every external user account to have a matching account in Unimus. You can create a user in User management > Users:

Where:

Username - the matching username for the external account in Active Directory.

Authentication method - LDAP.

Select access role - select which role the user will represent.

At this point, users should be able to log into Unimus using LDAP and their external account credentials.

Troubleshooting

There are generally two troubleshooting sources for any issue with LDAP AAA. Unimus log and AD debug logging on Windows Server. We actually recommend focusing on Unimus log, as it features full LDAP error codes without any additional configuration, which is not the case with AD debug logging (which requires manually specifying logging levels for all AD components).

Let's take a closer look at a couple of exemplary error messages you could encounter and their likely cause:

Ldap authentication failed: '10.20.30.40:389; nested exception is javax.naming.CommunicationException: 10.20.30.40:389 [Root exception is java.net.ConnectException: Connection refused (Connection refused)]'

This error indicates a wrong configuration (wrongly specified IP and / or port) or a network issue (likely a firewall).

Ldap authentication failed: '10.20.30.40:636; nested exception is javax.naming.CommunicationException: 10.20.30.40:636 [Root exception is javax.net.ssl.SSLHandshakeException: Remote host terminated the handshake]'

This error indicates an issue with LDAPS or StartTLS configuration, e.g. Unimus has LDAPS or StartTLS checked, but the server doesn't use either or is not set up for either, or the server is missing an SSL certificate for the LDAP server. In the latter case, refer to the section above where we mention what is required for a certificate to be recognized.

Ldap authentication failed: '[LDAP: error code 49 - 80090308: LdapErr: DSID-0C09041C, comment: AcceptSecurityContext error, data 52e, v4563]

This error indicates incorrect credentials. These can indicate any combination of wrong credentials (DN or password) for the access user or a wrong password provided for the Unimus user to be authenticated.

Ldap authentication failed: 'Incorrect result size: expected 1, actual 0'

This error indicates the access to LDAP was successful, but given the base DN and input in the username field, no match for the given user was found. Possible causes include:

• Wrong username input and / or the user was not found when searching under the Base DN. Check the username and / or the Base DN.
• The User Identifier is incorrectly configured. Check if the identifier is correct for your LDAP objects.
• The provided base DN does not contain a user identified by the configured User Identifier (similar to the 2 points above). Check if the user you want to auth has the identifier you are using.
• An LDAP filter specifying conditions the user does not comply with. Check if your filter properly returns the user you want to auth.

Final words

Hopefully this article can guide you through connecting Unimus with Active Directory via LDAP. If you have any questions, or you run into any issues, please feel free to post in the Support section of our forums, or contact us through our usual support channels.

In this guide we will look at how to monitor Unimus device job results in NetXMS, and how to create NetXMS alarms if a device doesn't have a valid backup within a specified timeframe. We will also explore how to run Unimus jobs directly from NetXMS.

Unimus & NetXMS integration

Running Unimus together with NetXMS creates a powerful ecosystem for both monitoring (NMS) and config management (NCM) of your infrastructure. You can integrate both solutions together - use data from NetXMS in Unimus, and vice-versa.

Unimus has a built-in NetXMS importer which allows Unimus to adopt nodes from NetXMS. This allows you to automate device ingestion in your network - both when you are first deploying the systems, as well when you add devices into your network. There is no need to add a device to Unimus and NetXMS separately, just add your device to NetXMS, and Unimus will automatically adopt it. You can read more about how to configure this on our Wiki.

In this article however, we want to look at how to integrate data from Unimus into NetXMS - how to see Unimus job statuses and device data in NetXMS, and how to trigger Unimus jobs directly from NetXMS.

Preparations

There are a few steps to do before we get started:

1) Enable Web Service Proxy in the NetXMS Agent of the node polling your network.

If you are not using Zones in NetXMS, this will be your NetXMS server. If you are using Zones, you will need to enable this on the Zone's proxy.

To enable the Web Services Proxy, we edit the Agent's config:

And add the appropriate setting EnableWebServiceProxy = yes in the config:

You need to restart the NetXMS Agent for this to take effect.

2) Create scripts required for Web Service Definitions, DCIs and Object Tools.

After the Web Service Proxy is enabled, we need to create a few scripts that other components in NetXMS will use. These scripts provide your Unimus server address the Unimus API token to DCIs and Object Tools which will later use them.

We have prepared an export of these scripts for you, available in the NetXMS Configuration Exports GitHub repo. You can simply download the export and import it in your NetXMS using Tools > Import Configuration...

We will import 4 scripts:

You will need to open the Unimus::getServerAddress script, and change the returned value to the URL of your Unimus Server.

You will also need to change the API Token in the Unimus::getApiToken script. You can generate an API token in Unimus in the User management > API tokens. Click the clipboard button to copy then token, and paste it as the return string in the NetXMS script.

3) Create Web Service Definitions.

Web Service Definitions are also available in the NetXMS Configuration Exports GitHub repo. After you import them, you should be able to see them in Configuration > Web Service Definitions:

Monitoring Unimus jobs in NetXMS

After the preparations above are finished, we can now import templates that use the Web Service Definitions to pull data from Unimus into NetXMS.

The NetXMS Configuration Exports GitHub repo contains a template export, which when exported creates 2 templates:

We have not included any Auto-Apply Rules in these templates, as each NetXMS deploy is usually quite unique in how nodes are structured. You can apply your own Auto-Apply Rules if you wish. For this article, we will just bind nodes to this template manually.

You should bind your networking devices to the Unimus device data template, and the Unimus Server node to the Unimus server status template. For the devices, you should see multiple DCIs created:

There is a threshold on the Unimus device last backup time DCI, which creates an alarm if a backup was not successful for the device in the last 3 days. You can change this threshold in the DCI config if you wish:

Triggering Unimus jobs from NetXMS

Next step is to create Object Tools which allow you to trigger Unimus jobs directly from NetXMS. The NetXMS Configuration Exports GitHub repo contains Object Tools, which should look like this when imported:

You should see the tools on your nodes under Commands:

If you wish, you can create Filters to make sure these tools are only available on Unimus-managed nodes. We have not included any due to the same reason as the Auto-Apply Rules on the templates.

Final words

Hopefully this article can serve as an example on how to integrate Unimus and NetXMS together. If you have any questions, or you run into any issues, please feel free to post in the Support section of our forums, or contact us through our usual support channels.