setup.php

<?php
/*
 +-------------------------------------------------------------------------+
 | Copyright (C) 2004-2026 The Cacti Group                                 |
 |                                                                         |
 | This program is free software; you can redistribute it and/or           |
 | modify it under the terms of the GNU General Public License             |
 | as published by the Free Software Foundation; either version 2          |
 | of the License, or (at your option) any later version.                  |
 |                                                                         |
 | This program is distributed in the hope that it will be useful,         |
 | but WITHOUT ANY WARRANTY; without even the implied warranty of          |
 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the           |
 | GNU General Public License for more details.                            |
 +-------------------------------------------------------------------------+
 | Cacti: The Complete RRDTool-based Graphing Solution                     |
 +-------------------------------------------------------------------------+
 | This code is designed, written, and maintained by the Cacti Group. See  |
 | about.php and/or the AUTHORS file for specific developer information.   |
 +-------------------------------------------------------------------------+
 | http://www.cacti.net/                                                   |
 +-------------------------------------------------------------------------+
*/

/**
 * Registers this plugin's hooks and permission realms with Cacti, then
 * creates/verifies its database schema and default site. Cacti plugin
 * API entry point invoked when the plugin is installed or
 * re-registered during an upgrade.
 *
 * @param bool $operator_initiated Whether this install is being run by
 *                                an operator interactively (true,
 *                                default) versus automatically during
 *                                an upgrade (false); affects
 *                                default-site seeding retry-state
 *                                handling and CLI warning output.
 *
 * @return bool True if a default site exists after setup completes,
 *              false otherwise.
 */
function plugin_mactrack_install($operator_initiated = true): bool {
	api_plugin_register_hook('mactrack', 'top_header_tabs',       'mactrack_show_tab',             'setup.php');
	api_plugin_register_hook('mactrack', 'top_graph_header_tabs', 'mactrack_show_tab',             'setup.php');
	api_plugin_register_hook('mactrack', 'config_arrays',         'mactrack_config_arrays',        'setup.php');
	api_plugin_register_hook('mactrack', 'draw_navigation_text',  'mactrack_draw_navigation_text', 'setup.php');
	api_plugin_register_hook('mactrack', 'config_form',           'mactrack_config_form',          'setup.php');
	api_plugin_register_hook('mactrack', 'config_settings',       'mactrack_config_settings',      'setup.php');
	api_plugin_register_hook('mactrack', 'poller_bottom',         'mactrack_poller_bottom',        'setup.php');
	api_plugin_register_hook('mactrack', 'page_head',             'mactrack_page_head',            'setup.php');

	// device hook: intercept on device save
	api_plugin_register_hook('mactrack', 'api_device_save', 'sync_cacti_to_mactrack', 'mactrack_actions.php');
	// device hook: Add a new dropdown Action for Device Management
	api_plugin_register_hook('mactrack', 'device_action_array', 'mactrack_device_action_array', 'mactrack_actions.php');
	// device hook: Device Management Action dropdown selected: prepare the list of devices for a confirmation request
	api_plugin_register_hook('mactrack', 'device_action_prepare', 'mactrack_device_action_prepare', 'mactrack_actions.php');
	// device hook: Device Management Action dropdown selected: execute list of device
	api_plugin_register_hook('mactrack', 'device_action_execute', 'mactrack_device_action_execute', 'mactrack_actions.php');

	mactrack_install_realms(true);

	$site_ready = mactrack_setup_table_new($operator_initiated);

	if (!$site_ready && PHP_SAPI === 'cli') {
		fwrite(STDERR, "WARNING: MacTrack installed without a Default site; review the Cacti log. The poller will retry with backoff.\n");
	}

	return $site_ready;
}

/**
 * Removes this plugin's default-site seeding retry-state settings.
 * Cacti plugin API entry point invoked when the plugin is uninstalled.
 *
 * @return bool Always true.
 */
function plugin_mactrack_uninstall(): bool {
	db_execute_prepared(
		'DELETE FROM settings WHERE name IN (?, ?, ?)',
		['mt_default_site_seed_pending', 'mt_default_site_seed_attempts', 'mt_default_site_seed_next_retry']
	);

	return true;
}

/**
 * Reads this plugin's version and metadata from its INFO file. Cacti
 * plugin API entry point used throughout the plugin to display version
 * information.
 *
 * @return array The parsed INFO file's 'info' section (name, author,
 *               homepage, version, etc.).
 *
 * @global array $config Cacti global configuration array; used to
 *                       locate the plugin's INFO file.
 */
function plugin_mactrack_version(): array {
	global $config;
	$info = (array) parse_ini_file($config['base_path'] . '/plugins/mactrack/INFO', true);

	return $info['info'] ?? [];
}

/**
 * Ensures the plugin's configuration/schema is up to date by delegating
 * to mactrack_check_upgrade(). Cacti plugin API entry point invoked on
 * relevant page loads to catch pending upgrades.
 *
 * @return bool Always true.
 */
function plugin_mactrack_check_config(): bool {
	// Here we will check to ensure everything is configured
	mactrack_check_upgrade();

	return true;
}

/**
 * Ensures the plugin's configuration/schema is up to date by delegating
 * to mactrack_check_upgrade(). Cacti plugin API entry point invoked
 * when the plugin is upgraded.
 *
 * @return bool Always false.
 */
function plugin_mactrack_upgrade(): bool {
	// Here we will upgrade to the newest version
	mactrack_check_upgrade();

	return false;
}

/**
 * Permission realms this plugin registers, keyed by realm display name,
 * each with its comma-delimited list of protected files. Shared by the
 * installer and by mactrack_realms_are_stale() so a page added to a realm
 * (for example the Dashboard) reaches upgraded installs.
 *
 * @return array<string, string> Realm display name => comma-delimited files.
 */
function mactrack_realm_definitions(): array {
	return [
		'Mactrack Viewer'        => 'mactrack_view_dashboard.php,mactrack_view_ips.php,mactrack_view_arp.php,mactrack_view_macs.php,mactrack_view_dot1x.php,mactrack_view_sites.php,mactrack_view_devices.php,mactrack_view_interfaces.php,mactrack_view_graphs.php,mactrack_ajax.php',
		'Mactrack Administrator' => 'mactrack_ajax_admin.php,mactrack_devices.php,mactrack_snmp.php,mactrack_sites.php,mactrack_device_types.php,mactrack_utilities.php,mactrack_macwatch.php,mactrack_macauth.php,mactrack_vendormacs.php',
	];
}

/**
 * Registers this plugin's permission realms with Cacti.
 *
 * Cacti's api_plugin_register_realm() maps a realm that has to be created to
 * the configured admin and to the user making the request when its fourth
 * argument is true. Repairs that run from an arbitrary Console page pass
 * false so that a missing realm is never granted to whoever triggered them.
 *
 * The name must keep "install": Cacti only honors api_plugin_register_realm()
 * when the calling function's name contains install, upgrade or setup.
 *
 * @param bool $grant_access Whether newly created realms are granted to the
 *                           admin and current session user.
 *
 * @return void
 */
function mactrack_install_realms(bool $grant_access): void {
	foreach (mactrack_realm_definitions() as $display => $files) {
		api_plugin_register_realm('mactrack', $files, $display, $grant_access);
	}
}

/**
 * Reports whether any file this plugin protects is missing from the realms
 * stored in plugin_realms. The realm file lists are only written when the
 * plugin is installed or its version changes, so a file added to a realm
 * without a version bump stays unmapped on upgraded installs and Cacti
 * denies it with "401 Permission Denied".
 *
 * @return bool True when at least one expected file is not registered.
 */
function mactrack_realms_are_stale(): bool {
	$rows       = db_fetch_assoc_prepared('SELECT file FROM plugin_realms WHERE plugin = ?', ['mactrack']);
	$registered = [];

	foreach ((array) $rows as $row) {
		foreach (explode(',', (string) $row['file']) as $file) {
			$registered[trim($file)] = true;
		}
	}

	foreach (mactrack_realm_definitions() as $files) {
		foreach (explode(',', $files) as $file) {
			if (!isset($registered[$file])) {
				return true;
			}
		}
	}

	return false;
}

/**
 * Detects a version mismatch between the running plugin code and the
 * version recorded in plugin_config, and when found (and only on a
 * small set of pages, to limit overhead), re-registers hooks, runs the
 * database upgrade, migrates legacy SNMP read strings, recreates
 * missing permission realms, renames legacy realm display names,
 * rebuilds cached scanning functions, and updates the stored plugin
 * version metadata. Always retries any pending default-site seeding at
 * the end.
 *
 * @return void
 *
 * @global array $config Cacti global configuration array; used to
 *                       locate library files to include.
 */
function mactrack_check_upgrade(): void {
	global $config;

	$files = ['index.php', 'plugins.php', 'mactrack_devices.php'];

	if (!in_array(get_current_page(), $files, true)) {
		return;
	}

	require_once($config['base_path'] . '/plugins/mactrack/includes/database.php');
	require_once($config['base_path'] . '/plugins/mactrack/lib/mactrack_functions.php');

	$current = plugin_mactrack_version();
	$current = $current['version'];

	$old     = (array) db_fetch_row("SELECT * FROM plugin_config WHERE directory='mactrack'");

	$version_changed = !cacti_sizeof($old) || $current != $old['version'];

	// A realm file list can drift from the code without a version bump (the
	// Dashboard was added that way). Repair only the realms in that case; the
	// full upgrade below rebuilds indexes and rewrites large tables.
	if (!$version_changed && in_array((int) $old['status'], [1, 4], true) && mactrack_realms_are_stale()) {
		mactrack_install_realms(false);
	}

	if ($version_changed) {
		// if the plugin is installed and/or active
		if (!cacti_sizeof($old) || $old['status'] == 1 || $old['status'] == 4) {
			// re-register the hooks
			plugin_mactrack_install(false);

			if (api_plugin_is_enabled('mactrack')) {
				// may sound ridiculous, but enables new hooks
				api_plugin_enable_hooks('mactrack');
			}

			// perform a database upgrade
			mactrack_database_upgrade();
		}

		if (read_config_option('mt_convert_readstrings', true) != 'on') {
			convert_readstrings();
		}

		// Remove files tombstoned in manifest.json plus the dev-only tests/ tree.
		mactrack_prune_files();

		// If are realms are not present in plugin_realms recreate them with the old realm ids (minus 100) so that upgraded installs are not broken
		if (!db_fetch_cell("SELECT id FROM plugin_realms WHERE plugin = 'mactrack'")) {
			db_execute("INSERT INTO plugin_realms
				(id, plugin, file, display)
				VALUES (2020, 'mactrack', 'mactrack_view_ips.php,mactrack_view_arp.php,mactrack_view_macs.php,mactrack_view_sites.php,mactrack_view_devices.php,mactrack_view_interfaces.php,mactrack_view_dot1x.php,mactrack_view_graphs.php,mactrack_ajax.php', 'Mactrack Viewer')");
			db_execute("INSERT INTO plugin_realms
				(id, plugin, file, display)
				VALUES (2021, 'mactrack', 'mactrack_ajax_admin.php,mactrack_devices.php,mactrack_snmp.php,mactrack_sites.php,mactrack_device_types.php,mactrack_utilities.php,mactrack_macwatch.php,mactrack_macauth.php,mactrack_vendormacs.php', 'Mactrack Administrator')");
		}

		// Change old names
		if (db_fetch_cell("SELECT count(*) FROM plugin_realms WHERE plugin = 'mactrack' and display='Device Tracking Viewer'")) {
			db_fetch_cell("UPDATE plugin_realms set display='Mactrack Viewer' WHERE plugin = 'mactrack' and display='Device Tracking Viewer'");
		}

		if (db_fetch_cell("SELECT count(*) FROM plugin_realms WHERE plugin = 'mactrack' and display='Device Tracking Administrator'")) {
			db_fetch_cell("UPDATE plugin_realms set display='Mactrack Administrator' WHERE plugin = 'mactrack' and display='Device Tracking Administrator'");
		}

		// rebuild the scanning functions
		mactrack_rebuild_scanning_funcs();

		// update the plugin information
		$info = plugin_mactrack_version();
		$id   = db_fetch_cell_prepared('SELECT id FROM plugin_config WHERE directory = ?', ['mactrack']);

		db_execute_prepared('UPDATE plugin_config
			SET name = ?,
			author = ?,
			webpage = ?,
			version = ?
			WHERE id = ?',
			[$info['longname'], $info['author'], $info['homepage'], $info['version'], $id]);
	}

	mactrack_retry_default_site();
}

/**
 * Checks whether a database table exists.
 *
 * @param string $table The table name to check.
 *
 * @return bool True if the table exists, false otherwise.
 */
function mactrack_db_table_exists($table): bool {
	return cacti_sizeof(db_fetch_assoc("SHOW TABLES LIKE '$table'")) > 0;
}

/**
 * Checks whether a column exists in a database table.
 *
 * @param string $table  The table name to check.
 * @param string $column The column name to check for.
 *
 * @return bool True if the table exists and has the given column,
 *              false otherwise.
 */
function mactrack_db_column_exists($table, $column): bool {
	$found = false;

	if (mactrack_db_table_exists($table)) {
		$columns  = db_fetch_assoc("SHOW COLUMNS FROM $table");

		if (cacti_sizeof($columns)) {
			foreach ($columns as $row) {
				if ($row['Field'] == $column) {
					$found = true;

					break;
				}
			}
		}
	}

	return $found;
}

/**
 * Checks whether a named index/key exists on a database table.
 *
 * @param string $table The table name to check.
 * @param string $index The index/key name to check for.
 *
 * @return bool True if the table exists and has the given index, false
 *              otherwise.
 */
function mactrack_db_key_exists($table, $index): bool {
	$found = false;

	if (mactrack_db_table_exists($table)) {
		$keys  = db_fetch_assoc("SHOW INDEXES FROM $table");

		if (cacti_sizeof($keys)) {
			foreach ($keys as $key) {
				if ($key['Key_name'] == $index) {
					$found = true;

					break;
				}
			}
		}
	}

	return $found;
}

/**
 * Executes an arbitrary SQL statement, discarding its result. Thin
 * wrapper used by the schema setup routines; $message is currently
 * unused but kept for call-site self-documentation.
 *
 * @param string $message Human-readable description of the operation
 *                        (unused).
 * @param string $syntax  The SQL statement to execute.
 *
 * @return void
 */
function mactrack_execute_sql($message, $syntax): void {
	$result = db_execute($syntax);
}

/**
 * Creates a database table if it doesn't already exist.
 *
 * @param string $table  The table name to check/create.
 * @param string $syntax The CREATE TABLE SQL statement to execute if
 *                      the table doesn't exist.
 *
 * @return void
 */
function mactrack_create_table($table, $syntax): void {
	if (!mactrack_db_table_exists($table)) {
		db_execute($syntax);
	}
}

/**
 * Adds a column to a database table if it doesn't already exist.
 *
 * @param string $table  The table name to check.
 * @param string $column The column name to check for.
 * @param string $syntax The ALTER TABLE SQL statement to execute if the
 *                      column doesn't exist.
 *
 * @return void
 */
function mactrack_add_column($table, $column, $syntax): void {
	if (!mactrack_db_column_exists($table, $column)) {
		db_execute($syntax);
	}
}

/**
 * Adds an index/key to a database table if it doesn't already exist.
 *
 * @param string $table  The table name to check.
 * @param string $index  The index/key name to check for.
 * @param string $syntax The ALTER TABLE SQL statement to execute if the
 *                      index doesn't exist.
 *
 * @return void
 */
function mactrack_add_index($table, $index, $syntax): void {
	if (!mactrack_db_key_exists($table, $index)) {
		db_execute($syntax);
	}
}

/**
 * Modifies an existing column in a database table (e.g. changing its
 * type/default), only if the column currently exists.
 *
 * @param string $table  The table name to check.
 * @param string $column The column name to check for.
 * @param string $syntax The ALTER TABLE SQL statement to execute if the
 *                      column exists.
 *
 * @return void
 */
function mactrack_modify_column($table, $column, $syntax): void {
	if (mactrack_db_column_exists($table, $column)) {
		db_execute($syntax);
	}
}

/**
 * Deletes a column from a database table, only if the column currently
 * exists.
 *
 * @param string $table  The table name to check.
 * @param string $column The column name to check for.
 * @param string $syntax The ALTER TABLE SQL statement to execute if the
 *                      column exists.
 *
 * @return void
 */
function mactrack_delete_column($table, $column, $syntax): void {
	if (mactrack_db_column_exists($table, $column)) {
		db_execute($syntax);
	}
}

/**
 * Checks whether this plugin's dependencies are satisfied. Cacti
 * plugin API hook point; currently always reports dependencies as
 * satisfied.
 *
 * @return bool Always true.
 *
 * @global array $plugins Cacti global list of installed plugins
 *                       (declared but not used directly here).
 * @global array $config  Cacti global configuration array (declared
 *                       but not used directly here).
 */
function mactrack_check_dependencies(): bool {
	global $plugins, $config;

	return true;
}

/**
 * Creates/updates the plugin's database tables and ensures a default
 * site exists, preserving any prior default-site seeding backoff state
 * across incomplete-upgrade re-entries into this hook (unless the
 * install is operator-initiated).
 *
 * @param bool $operator_initiated Whether this call is operator-
 *                                initiated (true, default) versus an
 *                                automatic upgrade re-entry (false).
 *
 * @return bool True if a default site exists after setup completes,
 *              false otherwise.
 *
 * @global array $config Cacti global configuration array; used to
 *                       locate the database include file.
 */
function mactrack_setup_table_new($operator_initiated = true): bool {
	global $config;

	require_once($config['base_path'] . '/plugins/mactrack/includes/database.php');

	// Preserve a prior failed seed's backoff when an incomplete upgrade causes
	// Cacti to re-enter this hook on a later request.
	if ($operator_initiated || read_config_option('mt_default_site_seed_pending', true) !== 'on') {
		mactrack_reset_default_site_retry();
	}

	return mactrack_setup_database(PHP_SAPI !== 'cli');
}

/**
 * Emits this plugin's JavaScript and CSS `<script>`/`<link>` tags into
 * the page head, using a theme-specific stylesheet when one exists for
 * the currently selected theme. Registered as the 'page_head' Cacti
 * hook.
 *
 * @return void
 *
 * @global array $config Cacti global configuration array; used to
 *                       build asset URLs and check for a theme-specific
 *                       stylesheet.
 */
function mactrack_page_head() {
	global $config;

	print get_md5_include_js('plugins/mactrack/js/mactrack.js');
	print get_md5_include_js('plugins/mactrack/js/mactrack_snmp.js');
	print get_md5_include_js('plugins/mactrack/js/cards.js');

	print get_md5_include_css('plugins/mactrack/css/cards.css');

	if (file_exists($config['base_path'] . '/plugins/mactrack/css/' . get_selected_theme() . '.css')) {
		print get_md5_include_css('plugins/mactrack/css/' . get_selected_theme() . '.css');
	} else {
		print get_md5_include_css('plugins/mactrack/css/mactrack.css');
	}
}

/**
 * Launches the MacTrack poller script (poller_mactrack.php) as a
 * background process. Registered as the 'poller_bottom' Cacti hook,
 * invoked at the end of each Cacti poller cycle.
 *
 * @return void
 *
 * @global array $config Cacti global configuration array; used to
 *                       build the poller script's path.
 */
function mactrack_poller_bottom() {
	global $config;

	$command_string = read_config_option('path_php_binary');
	$extra_args     = '-q ' . $config['base_path'] . '/plugins/mactrack/poller_mactrack.php';
	exec_background($command_string, $extra_args);
}

/**
 * Builds this plugin's Console "Settings > Mactrack" configuration
 * tab's field definitions (scanning frequency, concurrent processes,
 * data retention, notification policies, etc.). Registered as the
 * 'config_settings' Cacti hook.
 *
 * @return void
 *
 * @global array $tabs                          Cacti settings tabs
 *                                              registry; a 'mactrack'
 *                                              entry is added.
 * @global array $settings                      Cacti settings field
 *                                              registry; a 'mactrack'
 *                                              section is added.
 * @global array $settings_user                 Reserved/declared for
 *                                              parity with other
 *                                              functions in this file;
 *                                              not used directly here.
 * @global array $tabs_graphs                   Reserved/declared for
 *                                              parity with other
 *                                              functions in this file;
 *                                              not used directly here.
 * @global array $snmp_versions                 SNMP version option
 *                                              list used by SNMP-
 *                                              related settings
 *                                              fields.
 * @global array $mactrack_poller_frequencies   Scanning frequency
 *                                              option list.
 * @global array $mactrack_data_retention        Data retention option
 *                                              list.
 * @global array $mactrack_macauth_frequencies   MAC auth report
 *                                              frequency option list.
 * @global array $mactrack_update_policies       Cacti/MacTrack sync
 *                                              policy option list.
 */
function mactrack_config_settings() {
	global $tabs, $settings, $settings_user, $tabs_graphs, $snmp_versions, $mactrack_poller_frequencies,
	$mactrack_data_retention, $mactrack_macauth_frequencies, $mactrack_update_policies;

	$tabs['mactrack'] = __('Mactrack', 'mactrack');

	$settings['mactrack'] = [
		'mactrack_hdr_timing' => [
			'friendly_name' => __('General Settings', 'mactrack'),
			'method'        => 'spacer',
		],
		'mt_collection_timing' => [
			'friendly_name' => __('Scanning Frequency', 'mactrack'),
			'description'   => __('Choose when to collect MAC and IP Addresses and Interface statistics from your network devices.', 'mactrack'),
			'method'        => 'drop_array',
			'default'       => 'disabled',
			'array'         => $mactrack_poller_frequencies,
		],
		'mt_processes' => [
			'friendly_name' => __('Concurrent Processes', 'mactrack'),
			'description'   => __('Specify how many devices will be polled simultaneously until all devices have been polled.', 'mactrack'),
			'default'       => '7',
			'method'        => 'textbox',
			'max_length'    => '10',
			'size'          => '4'
		],
		'mt_script_runtime' => [
			'friendly_name' => __('Scanner Max Runtime', 'mactrack'),
			'description'   => __('Specify the number of minutes a device scanning function will be allowed to run prior to the system assuming it has been completed.  This setting will correct for abended scanning jobs.', 'mactrack'),
			'default'       => '20',
			'method'        => 'textbox',
			'max_length'    => '10',
			'size'          => '4'
		],
		'mt_base_time' => [
			'friendly_name' => __('Start Time for Data Collection', 'mactrack'),
			'description'   => __('When would you like the first data collection to take place.  All future data collection times will be based upon this start time.  A good example would be 12:00AM.', 'mactrack'),
			'default'       => '1:00am',
			'method'        => 'textbox',
			'max_length'    => '10',
			'size'          => '8'
		],
		'mt_maint_time' => [
			'friendly_name' => __('Database Maintenance Time', 'mactrack'),
			'description'   => __('When should old database records be removed from the database.  Please note that no access will be permitted to the port database while this action is taking place.', 'mactrack'),
			'default'       => '12:00am',
			'method'        => 'textbox',
			'max_length'    => '10',
			'size'          => '8'
		],
		'mt_maint_confirm' => [
			'friendly_name' => __('Confirm Utilities Prompt', 'mactrack'),
			'description'   => __('When using utilities, prompt for verification', 'mactrack'),
			'default'       => read_config_option('deletion_verification'),
			'method'        => 'checkbox',
		],
		'mt_data_retention' => [
			'friendly_name' => __('Data Retention', 'mactrack'),
			'description'   => __('How long should port MAC details be retained in the database.', 'mactrack'),
			'method'        => 'drop_array',
			'default'       => '14',
			'array'         => $mactrack_data_retention,
		],
		'mt_data_retention_ip' => [
			'friendly_name' => __('Data Retention IPs', 'mactrack'),
			'description'   => __('How long should discovered IPs details be retained in the database.', 'mactrack'),
			'method'        => 'drop_array',
			'default'       => '3',
			'array'         => $mactrack_data_retention,
		],
		'mt_ignorePorts_delim' => [
			'friendly_name' => __('Switch Level Ignore Ports Delimiter', 'mactrack'),
			'description'   => __('What delimiter should Mactrack use when parsing the Ignore Ports string for each switch.', 'mactrack'),
			'method'        => 'drop_array',
			'default'       => '-1',
			'array'         => [
				'-1' => __('Auto Detect', 'mactrack'),
				':'  => __('Colon [:]', 'mactrack'),
				'|'  => __('Pipe [|]', 'mactrack'),
				' '  => __('Space [ ]', 'mactrack')
			]
		],
		'mt_mac_format' => [
			'friendly_name' => __('Mac Address Output Format', 'mactrack'),
			'description'   => __('Format used for display.', 'mactrack'),
			'method'        => 'drop_array',
			'default'       => 'aa:bb:cc:dd:ee:ff',
			'array'         => [
				'aa:bb:cc:dd:ee:ff' => 'aa:bb:cc:dd:ee:ff',
				'aa-bb-cc-dd-ee-ff' => 'aa-bb-cc-dd-ee-ff',
				'aabb-ccdd-eeff'    => 'aabb-ccdd-eeff',
				'aabbccddeeff'      => 'aabbccddeeff',
				'aabb.ccdd.eeff'    => 'aabb.ccdd.eeff'
			]
		],
		'mt_ignorePorts' => [
			'method'        => 'textbox',
			'friendly_name' => __('Ports to Ignore', 'mactrack'),
			'description'   => __('Provide a regular expression of ifNames or ifDescriptions of ports to ignore in the interface list.  For example, (Vlan|Loopback|Null).', 'mactrack'),
			'class'         => 'textAreaNotes',
			'defaults'      => '(Vlan|Loopback|Null)',
			'max_length'    => '255',
			'size'          => '80'
		],
		'mt_interface_high' => [
			'friendly_name' => __('Bandwidth Usage Threshold', 'mactrack'),
			'description'   => __('When reviewing network interface statistics, what bandwidth threshold do you want to view by default.', 'mactrack'),
			'method'        => 'drop_array',
			'default'       => '70',
			'array'         => [
				'-1' => __('N/A', 'mactrack'),
				'10' => __('%d Percent', 10, 'mactrack'),
				'20' => __('%d Percent', 20, 'mactrack'),
				'30' => __('%d Percent', 30, 'mactrack'),
				'40' => __('%d Percent', 40, 'mactrack'),
				'50' => __('%d Percent', 50, 'mactrack'),
				'60' => __('%d Percent', 60, 'mactrack'),
				'70' => __('%d Percent', 70, 'mactrack'),
				'80' => __('%d Percent', 80, 'mactrack'),
				'90' => __('%d Percent', 90, 'mactrack')
			]
		],
		'mt_hdr_rdns' => [
			'friendly_name' => __('DNS Settings', 'mactrack'),
			'method'        => 'spacer',
		],
		'mt_reverse_dns' => [
			'friendly_name' => __('Perform Reverse DNS Name Resolution', 'mactrack'),
			'description'   => __('Should Mactrack perform reverse DNS lookup of the IP addresses associated with ports. CAUTION: If DNS is not properly setup, this will slow scan time significantly.', 'mactrack'),
			'default'       => '',
			'method'        => 'checkbox'
		],
		'mt_dns_primary' => [
			'friendly_name' => __('Primary DNS IP Address', 'mactrack'),
			'description'   => __('Enter the primary DNS IP Address to utilize for reverse lookups.', 'mactrack'),
			'method'        => 'textbox',
			'default'       => '',
			'max_length'    => '30',
			'size'          => '18'
		],
		'mt_dns_secondary' => [
			'friendly_name' => __('Secondary DNS IP Address', 'mactrack'),
			'description'   => __('Enter the secondary DNS IP Address to utilize for reverse lookups.', 'mactrack'),
			'method'        => 'textbox',
			'default'       => '',
			'max_length'    => '30',
			'size'          => '18'
		],
		'mt_dns_timeout' => [
			'friendly_name' => __('DNS Timeout', 'mactrack'),
			'description'   => __('Please enter the DNS timeout in milliseconds. Mactrack uses a PHP based DNS resolver.', 'mactrack'),
			'method'        => 'textbox',
			'default'       => '500',
			'max_length'    => '10',
			'size'          => '4'
		],
		'mt_dns_prime_interval' => [
			'friendly_name' => __('DNS Prime Interval', 'mactrack'),
			'description'   => __('How often, in seconds do Mactrack scanning IP\'s need to be resolved to MAC addresses for DNS resolution.  Using a larger number when you have several thousand devices will increase performance.', 'mactrack'),
			'method'        => 'textbox',
			'default'       => '120',
			'max_length'    => '10',
			'size'          => '4'
		],
		'mactrack_hdr_notification' => [
			'friendly_name' => __('Notification Settings', 'mactrack'),
			'method'        => 'spacer',
		],
		'mt_from_email' => [
			'friendly_name' => __('Source Address', 'mactrack'),
			'description'   => __('The source Email address for Mactrack Emails.', 'mactrack'),
			'method'        => 'textbox',
			'default'       => '',
			'max_length'    => '100',
			'size'          => '30'
		],
		'mt_from_name' => [
			'friendly_name' => __('Source Email Name', 'mactrack'),
			'description'   => __('The Source Email name for Mactrack Emails.', 'mactrack'),
			'method'        => 'textbox',
			'default'       => __('MACTrack Administrator', 'mactrack'),
			'max_length'    => '100',
			'size'          => '30'
		],
		'mt_macwatch_description' => [
			'friendly_name' => __('MacWatch Default Body', 'mactrack'),
			'description'   => htmlspecialchars(__('The Email body preset for Mactrack MacWatch Emails.  The body can contain ' .
			'any valid html tags.  It also supports replacement tags that will be processed when sending an Email.  ' .
			'Valid tags include <IP>, <MAC>, <TICKET>, <SITENAME>, <DEVICEIP>, <PORTNAME>, <PORTNUMBER>, <DEVICENAME>.', 'mactrack')),
			'method'        => 'textarea',
			'default'       => __('Mac Address <MAC> found at IP Address <IP> for Ticket Number: <TICKET>.<br>The device is located at<br>Site: <SITENAME>, Device <DEVICENAME>, IP <DEVICEIP>, Port <PORTNUMBER>, and Port Name <PORTNAME>', 'mactrack'),
			'class'         => 'textAreaNotes',
			'max_length'    => '512',
			'textarea_rows' => '5',
			'textarea_cols' => '80',
		],
		'mt_macauth_emails' => [
			'friendly_name' => __('MacAuth Report Email Addresses', 'mactrack'),
			'description'   => __('A comma delimited list of users to receive the MacAuth Email notifications.', 'mactrack'),
			'method'        => 'textarea',
			'default'       => '',
			'class'         => 'textAreaNotes',
			'max_length'    => '255',
			'textarea_rows' => '5',
			'textarea_cols' => '80',
		],
		'mt_macauth_email_frequency' => [
			'friendly_name' => __('MacAuth Report Frequency', 'mactrack'),
			'description'   => __('How often will the MacAuth Reports be Emailed.', 'mactrack'),
			'method'        => 'drop_array',
			'default'       => 'disabled',
			'array'         => $mactrack_macauth_frequencies,
		],
		'mactrack_hdr_arpwatch' => [
			'friendly_name' => __('Mactrack ArpWatch Settings', 'mactrack'),
			'method'        => 'spacer',
		],
		'mt_arpwatch' => [
			'friendly_name' => __('Enable ArpWatch', 'mactrack'),
			'description'   => __('Should Mactrack also use ArpWatch data to supplement Mac to IP/DNS resolution?', 'mactrack'),
			'default'       => '',
			'method'        => 'checkbox'
		],
		'mt_arpwatch_path' => [
			'friendly_name' => __('ArpWatch Database Path', 'mactrack'),
			'description'   => __('The location of the ArpWatch Database file on the Cacti server.', 'mactrack'),
			'method'        => 'filepath',
			'default'       => '',
			'max_length'    => '255',
			'size'          => '60'
		],
		'mactrack_hdr_general' => [
			'friendly_name' => __('SNMP Presets', 'mactrack'),
			'method'        => 'spacer',
		],
		'mt_update_policy' => [
			'friendly_name' => __('Update Policy for SNMP Options', 'mactrack'),
			'description'   => __('Policy for synchronization of SNMP Options between Cacti devices and Mactrack Devices.', 'mactrack'),
			'method'        => 'drop_array',
			'default'       => 1,
			'array'         => $mactrack_update_policies,
		],
		'mt_snmp_ver' => [
			'friendly_name' => __('Version', 'mactrack'),
			'description'   => __('Default SNMP version for all new hosts.', 'mactrack'),
			'method'        => 'drop_array',
			'default'       => '2',
			'array'         => $snmp_versions,
		],
		'mt_snmp_community' => [
			'friendly_name' => __('Community', 'mactrack'),
			'description'   => __('Default SNMP read community for all new hosts.', 'mactrack'),
			'method'        => 'textbox',
			'default'       => 'public',
			'max_length'    => '100',
			'size'          => '20'
		],
		'mt_snmp_communities' => [
			'friendly_name' => __('Communities', 'mactrack'),
			'description'   => __('Fill in the list of available SNMP read strings to test for this device. Each read string must be separated by a colon \':\'.  These read strings will be tested sequentially if the primary read string is invalid.', 'mactrack'),
			'method'        => 'textbox',
			'default'       => 'public:private:secret',
			'max_length'    => '255'
		],
		'mt_snmp_port' => [
			'friendly_name' => __('Port', 'mactrack'),
			'description'   => __('The UDP/TCP Port to poll the SNMP agent on.', 'mactrack'),
			'method'        => 'textbox',
			'default'       => '161',
			'max_length'    => '10',
			'size'          => '4'
		],
		'mt_snmp_timeout' => [
			'friendly_name' => __('Timeout', 'mactrack'),
			'description'   => __('Default SNMP timeout in milli-seconds.', 'mactrack'),
			'method'        => 'textbox',
			'default'       => '500',
			'max_length'    => '10',
			'size'          => '4'
		],
		'mt_snmp_retries' => [
			'friendly_name' => __('Retries', 'mactrack'),
			'description'   => __('The number times the SNMP poller will attempt to reach the host before failing.', 'mactrack'),
			'method'        => 'textbox',
			'default'       => '3',
			'max_length'    => '10',
			'size'          => '4'
		]
	];

	$ts = [];

	foreach ($settings['path'] as $t => $ta) {
		$ts[$t] = $ta;

		if ($t == 'path_snmpget') {
			$ts['path_snmpbulkwalk'] = [
				'friendly_name' => __('snmpbulkwalk Binary Path', 'mactrack'),
				'description'   => __('The path to your snmpbulkwalk binary.', 'mactrack'),
				'method'        => 'textbox',
				'max_length'    => '255'
			];
		}
	}
	$settings['path'] = $ts;

	$tabs_graphs += ['mactrack' => __('MacTrack Settings', 'mactrack')];

	$settings_user += [
		'mactrack' => [
			'default_mactrack_tab' => [
				'friendly_name' => __('Default Tab', 'mactrack'),
				'description'   => __('Which MacTrack tab would you want to be your Default tab every time you goto the MacTrack second.', 'mactrack'),
				'method'        => 'drop_array',
				'default'       => 'sites',
				'array'         => [
					'sites'      => __('Sites', 'mactrack'),
					'devices'    => __('Devices', 'mactrack'),
					'ips'        => __('IP Addresses', 'mactrack'),
					'macs'       => __('Mac Addresses', 'mactrack'),
					'interfaces' => __('Interfaces', 'mactrack'),
					'dot1x'      => __('dot1x Deta', 'mactrack')
				]
			]
		]
	];

	$settings['mail'] += [
		'settings_proxy_header' => [
			'friendly_name' => __('Internet Proxy Settings'),
			'collapsible'   => 'true',
			'method'        => 'spacer',
		],
		'settings_proxy_server' => [
			'friendly_name' => __('Internet Proxy Address'),
			'description'   => __('For either core Cacti Services or Plugins that require internet access, enter the proxy server and port here in the following format IP:PORT.  For example 192.168.1.1:8080.'),
			'method'        => 'textbox',
			'default'       => '',
			'max_length'    => '30',
			'size'          => '30'
		],
		'settings_proxy_user' => [
			'friendly_name' => __('Internet Proxy User'),
			'description'   => __('If your Internet Proxy requires a username, enter it here.'),
			'method'        => 'textbox',
			'default'       => '',
			'max_length'    => '30',
			'size'          => '10'
		],
		'settings_proxy_password' => [
			'friendly_name' => __('Internet Proxy Password'),
			'description'   => __('If your Internet Proxy requires a password, enter it here.'),
			'method'        => 'textbox_password',
			'default'       => '',
			'max_length'    => '30',
			'size'          => '10'
		],
	];

	mactrack_check_upgrade();
}

/**
 * Registers this plugin's pages (devices, SNMP options, sites, device
 * types, utilities, mac watch, mac auth, vendor macs, and their
 * sub-actions/edit views) into Cacti's breadcrumb navigation array.
 * Registered as the 'draw_navigation_text' Cacti hook.
 *
 * @param array $nav The existing navigation entries array, keyed by
 *                   "file.php:action".
 *
 * @return array The navigation entries array with this plugin's pages
 *               added.
 */
function mactrack_draw_navigation_text($nav) {
	$nav['mactrack_view_dashboard.php:'] = [
		'title'   => __('Mactrack Dashboard', 'mactrack'),
		'mapping' => '',
		'url'     => 'mactrack_view_dashboard.php',
		'level'   => '0'
	];

	$nav['mactrack_devices.php:'] = [
		'title'   => __('Mactrack Devices', 'mactrack'),
		'mapping' => 'index.php:',
		'url'     => 'mactrack_devices.php',
		'level'   => '1'
	];

	$nav['mactrack_devices.php:edit'] = [
		'title'   => __('(Edit)', 'mactrack'),
		'mapping' => 'index.php:,mactrack_devices.php:',
		'url'     => '',
		'level'   => '2'
	];

	$nav['mactrack_devices.php:import'] = [
		'title'   => __('(Import)', 'mactrack'),
		'mapping' => 'index.php:,mactrack_devices.php:',
		'url'     => '',
		'level'   => '2'
	];

	$nav['mactrack_devices.php:actions'] = [
		'title'   => __('Actions', 'mactrack'),
		'mapping' => 'index.php:,mactrack_devices.php:',
		'url'     => '',
		'level'   => '2'
	];

	$nav['mactrack_snmp.php:'] = [
		'title'   => __('Mactrack SNMP Options', 'mactrack'),
		'mapping' => 'index.php:',
		'url'     => 'mactrack_snmp.php',
		'level'   => '1'
	];

	$nav['mactrack_snmp.php:actions'] = [
		'title'   => __('Actions', 'mactrack'),
		'mapping' => 'index.php:,mactrack_snmp.php:',
		'url'     => '',
		'level'   => '2'
	];

	$nav['mactrack_snmp.php:edit'] = [
		'title'   => __('(Edit)', 'mactrack'),
		'mapping' => 'index.php:,mactrack_snmp.php:',
		'url'     => '',
		'level'   => '2'
	];

	$nav['mactrack_snmp.php:item_edit'] = [
		'title'   => __('(Edit)', 'mactrack'),
		'mapping' => 'index.php:,mactrack_snmp.php:',
		'url'     => '',
		'level'   => '2'
	];

	$nav['mactrack_device_types.php:'] = [
		'title'   => __('Mactrack Device Types', 'mactrack'),
		'mapping' => 'index.php:',
		'url'     => 'mactrack_device_types.php',
		'level'   => '1'
	];

	$nav['mactrack_device_types.php:edit'] = [
		'title'   => __('(Edit)', 'mactrack'),
		'mapping' => 'index.php:,mactrack_device_types.php:',
		'url'     => '',
		'level'   => '2'
	];

	$nav['mactrack_device_types.php:import'] = [
		'title'   => __('(Import)', 'mactrack'),
		'mapping' => 'index.php:,mactrack_device_types.php:',
		'url'     => '',
		'level'   => '2'
	];

	$nav['mactrack_device_types.php:actions'] = [
		'title'   => __('Actions', 'mactrack'),
		'mapping' => 'index.php:,mactrack_device_types.php:',
		'url'     => '',
		'level'   => '2'
	];

	$nav['mactrack_sites.php:'] = [
		'title'   => __('Mactrack Sites', 'mactrack'),
		'mapping' => 'index.php:',
		'url'     => 'mactrack_sites.php',
		'level'   => '1'
	];

	$nav['mactrack_sites.php:edit'] = [
		'title'   => __('(Edit)', 'mactrack'),
		'mapping' => 'index.php:,mactrack_sites.php:',
		'url'     => '',
		'level'   => '2'
	];

	$nav['mactrack_sites.php:actions'] = [
		'title'   => __('Actions', 'mactrack'),
		'mapping' => 'index.php:,mactrack_sites.php:',
		'url'     => '',
		'level'   => '2'
	];

	$nav['mactrack_macwatch.php:'] = [
		'title'   => __('Mac Address Tracking Utility', 'mactrack'),
		'mapping' => 'index.php:',
		'url'     => 'mactrack_macwatch.php',
		'level'   => '1'
	];

	$nav['mactrack_macwatch.php:edit'] = [
		'title'   => __('(Edit)', 'mactrack'),
		'mapping' => 'index.php:,mactrack_macwatch.php:',
		'url'     => '',
		'level'   => '2'
	];

	$nav['mactrack_macwatch.php:actions'] = [
		'title'   => __('Actions', 'mactrack'),
		'mapping' => 'index.php:,mactrack_macwatch.php:',
		'url'     => '',
		'level'   => '2'
	];

	$nav['mactrack_macauth.php:'] = [
		'title'   => __('Mac Address Authorization Utility', 'mactrack'),
		'mapping' => 'index.php:',
		'url'     => 'mactrack_macauth.php',
		'level'   => '1'
	];

	$nav['mactrack_macauth.php:edit'] = [
		'title'   => __('(Edit)', 'mactrack'),
		'mapping' => 'index.php:,mactrack_macauth.php:',
		'url'     => '',
		'level'   => '2'
	];

	$nav['mactrack_macauth.php:actions'] = [
		'title'   => __('Actions', 'mactrack'),
		'mapping' => 'index.php:,mactrack_macauth.php:',
		'url'     => '',
		'level'   => '2'
	];

	$nav['mactrack_vendormacs.php:'] = [
		'title'   => __('Mactrack Vendor Macs', 'mactrack'),
		'mapping' => 'index.php:',
		'url'     => 'mactrack_vendormacs.php',
		'level'   => '1'
	];

	$nav['mactrack_view_macs.php:'] = [
		'title'   => __('Mactrack View Macs', 'mactrack'),
		'mapping' => '',
		'url'     => 'mactrack_view_macs.php',
		'level'   => '0'
	];

	$nav['mactrack_view_macs.php:actions'] = [
		'title'   => __('Actions', 'mactrack'),
		'mapping' => 'mactrack_view_macs.php:',
		'url'     => '',
		'level'   => '1'
	];

	$nav['mactrack_view_dot1x.php:'] = [
		'title'   => __('Mactrack Dot1x View', 'mactrack'),
		'mapping' => '',
		'url'     => 'mactrack_view_dot1x.php',
		'level'   => '0'
	];

	$nav['mactrack_view_arp.php:'] = [
		'title'   => __('Mactrack IP Address Viewer', 'mactrack'),
		'mapping' => '',
		'url'     => 'mactrack_view_arp.php',
		'level'   => '0'
	];

	$nav['mactrack_view_interfaces.php:'] = [
		'title'   => __('Mactrack View Interfaces', 'mactrack'),
		'mapping' => '',
		'url'     => 'mactrack_view_interfaces.php',
		'level'   => '0'
	];

	$nav['mactrack_view_sites.php:'] = [
		'title'   => __('Mactrack View Sites', 'mactrack'),
		'mapping' => '',
		'url'     => 'mactrack_view_sites.php',
		'level'   => '0'
	];

	$nav['mactrack_view_ips.php:'] = [
		'title'   => __('Mactrack View IP Ranges', 'mactrack'),
		'mapping' => '',
		'url'     => 'mactrack_view_ips.php',
		'level'   => '0'
	];

	$nav['mactrack_view_devices.php:'] = [
		'title'   => __('Mactrack View Devices', 'mactrack'),
		'mapping' => '',
		'url'     => 'mactrack_view_devices.php',
		'level'   => '0'
	];

	$nav['mactrack_utilities.php:'] = [
		'title'   => __('Mactrack Utilities', 'mactrack'),
		'mapping' => 'index.php:',
		'url'     => 'mactrack_utilities.php',
		'level'   => '1'
	];

	$nav['mactrack_utilities.php:mactrack_utilities_perform_db_maint'] = [
		'title'   => __('Perform Database Maintenance', 'mactrack'),
		'mapping' => 'index.php:,mactrack_utilities.php:',
		'url'     => 'mactrack_utilities.php',
		'level'   => '2'
	];

	$nav['mactrack_utilities.php:mactrack_utilities_purge_scanning_funcs'] = [
		'title'   => __('Refresh Scanning Functions', 'mactrack'),
		'mapping' => 'index.php:,mactrack_utilities.php:',
		'url'     => 'mactrack_utilities.php',
		'level'   => '2'
	];

	$nav['mactrack_utilities.php:mactrack_utilities_truncate_ports_table'] = [
		'title'   => __('Truncate Port Results Table', 'mactrack'),
		'mapping' => 'index.php:,mactrack_utilities.php:',
		'url'     => 'mactrack_utilities.php',
		'level'   => '2'
	];

	$nav['mactrack_utilities.php:mactrack_utilities_purge_aggregated_data'] = [
		'title'   => __('Truncate Aggregated Port Results Table', 'mactrack'),
		'mapping' => 'index.php:,mactrack_utilities.php:',
		'url'     => 'mactrack_utilities.php',
		'level'   => '2'
	];

	$nav['mactrack_utilities.php:mactrack_utilities_recreate_aggregated_data'] = [
		'title'   => __('Truncate and Re-create Aggregated Port Results Table', 'mactrack'),
		'mapping' => 'index.php:,mactrack_utilities.php:',
		'url'     => 'mactrack_utilities.php',
		'level'   => '2'
	];

	$nav['mactrack_utilities.php:mactrack_proc_status'] = [
		'title'   => __('View Mactrack Process Status', 'mactrack'),
		'mapping' => 'index.php:,mactrack_utilities.php:',
		'url'     => 'mactrack_utilities.php',
		'level'   => '2'
	];

	$nav['mactrack_utilities.php:mactrack_refresh_oui_database'] = [
		'title'   => __('Refresh/Update Vendor MAC Database from IEEE', 'mactrack'),
		'mapping' => 'index.php:,mactrack_utilities.php:',
		'url'     => 'mactrack_utilities.php',
		'level'   => '2'
	];

	$nav['mactrack_view_graphs.php:'] = [
		'title'   => __('Mactrack Graph Viewer', 'mactrack'),
		'mapping' => '',
		'url'     => 'mactrack_view_graphs.php',
		'level'   => '0'
	];

	$nav['mactrack_view_graphs.php:preview'] = [
		'title'   => __('Mactrack Graph Viewer', 'mactrack'),
		'mapping' => '',
		'url'     => 'mactrack_view_graphs.php',
		'level'   => '0'
	];

	return $nav;
}

/**
 * Renders this plugin's tab icon/link in the graph/console header tab
 * bar (linking to the currently selected MacTrack report view), shown
 * only to users with view permission. Registered as the
 * 'top_header_tabs' and 'top_graph_header_tabs' Cacti hooks.
 *
 * @return void
 *
 * @global array $config                     Cacti global configuration
 *                                          array; used to build asset
 *                                          and page URLs.
 * @global array $user_auth_realm_filenames Reserved/declared for parity
 *                                          with other functions in this
 *                                          file; not used directly
 *                                          here.
 */
function mactrack_show_tab() {
	global $config, $user_auth_realm_filenames;

	require_once($config['base_path'] . '/plugins/mactrack/lib/mactrack_functions.php');

	if (!isset_request_var('report')) {
		set_request_var('report', 'sites');
	}

	if (api_user_realm_auth('mactrack_view_macs.php')) {
		if (substr_count($_SERVER['REQUEST_URI'], 'mactrack_view_')) {
			print '<a href="' . html_escape($config['url_path'] . 'plugins/mactrack/mactrack_view_' . get_nfilter_request_var('report') . '.php') . '"><img src="' . $config['url_path'] . 'plugins/mactrack/images/tab_mactrack_down.png" alt="' . __('MacTrack', 'mactrack') . '"></a>';
		} else {
			print '<a href="' . html_escape($config['url_path'] . 'plugins/mactrack/mactrack_view_' . get_nfilter_request_var('report') . '.php') . '"><img src="' . $config['url_path'] . 'plugins/mactrack/images/tab_mactrack.png" alt="' . __('MacTrack', 'mactrack') . '"></a>';
		}
	}
}

/**
 * Populates the various global lookup/option arrays used throughout
 * this plugin (device types, search filter types, poller frequencies,
 * data retention options, MAC auth report frequencies, duplex/update
 * policy options, refresh intervals) and registers this plugin's
 * Console menu entries and icon glyphs. Registered as the
 * 'config_arrays' Cacti hook.
 *
 * @return void
 *
 * @global array  $mactrack_device_types        Device type option
 *                                              list; populated here.
 * @global array  $mactrack_search_types        Filter-type option
 *                                              list; populated here.
 * @global array  $messages                     Cacti flash-message
 *                                              registry; a pending
 *                                              session message is
 *                                              surfaced here.
 * @global array  $menu                         Cacti Console menu
 *                                              registry; this plugin's
 *                                              entries are added.
 * @global array  $menu_glyphs                  Cacti Console menu icon
 *                                              registry; this plugin's
 *                                              icons are added.
 * @global array  $config                       Cacti global
 *                                              configuration array.
 * @global array  $rows_selector                Reserved/declared for
 *                                              parity with other
 *                                              functions in this file;
 *                                              not used directly here.
 * @global array  $mactrack_poller_frequencies  Scanning frequency
 *                                              option list; populated
 *                                              here.
 * @global array  $mactrack_data_retention      Data retention option
 *                                              list; populated here.
 * @global int    $refresh_interval             Refresh interval option
 *                                              list; populated here.
 * @global array  $mactrack_macauth_frequencies MAC auth report
 *                                              frequency option list;
 *                                              populated here.
 * @global array  $mactrack_duplexes            Duplex option list;
 *                                              populated here.
 * @global array  $mactrack_update_policies     Cacti/MacTrack sync
 *                                              policy option list;
 *                                              populated here.
 */
function mactrack_config_arrays() {
	global $mactrack_device_types, $mactrack_search_types, $messages;
	global $menu, $menu_glyphs, $config, $rows_selector;
	global $mactrack_poller_frequencies, $mactrack_data_retention, $refresh_interval;
	global $mactrack_macauth_frequencies, $mactrack_duplexes, $mactrack_update_policies;

	if (isset($_SESSION['mactrack_message']) && $_SESSION['mactrack_message'] != '') {
		$messages['mactrack_message'] = ['message' => $_SESSION['mactrack_message'], 'type' => 'info'];
		kill_session_var('mactrack_message');
	}

	$refresh_interval = [
		5   => __('%d Seconds', 5, 'mactrack'),
		10  => __('%d Seconds', 10, 'mactrack'),
		20  => __('%d Seconds', 20, 'mactrack'),
		30  => __('%d Seconds', 30, 'mactrack'),
		60  => __('%d Minute', 1, 'mactrack'),
		300 => __('%d Minutes', 5, 'mactrack')
	];

	$mactrack_device_types = [
		1 => __('Switch/Hub', 'mactrack'),
		2 => __('Switch/Router', 'mactrack'),
		3 => __('Router', 'mactrack')
	];

	$mactrack_search_types = [
		1 => '',
		2 => __('Matches', 'mactrack'),
		3 => __('Contains', 'mactrack'),
		4 => __('Begins With', 'mactrack'),
		5 => __('Does Not Contain', 'mactrack'),
		6 => __('Does Not Begin With', 'mactrack'),
		7 => __('Is Null', 'mactrack'),
		8 => __('Is Not Null', 'mactrack')
	];

	$mactrack_duplexes = [
		1 => __('Unknown', 'mactrack'),
		2 => __('Half', 'mactrack'),
		3 => __('Full', 'mactrack')
	];

	$mactrack_update_policies = [
		1 => __('None', 'mactrack'),
		2 => __('Sync Cacti Device to Mactrack Device', 'mactrack'),
		3 => __('Sync Mactrack Device to Cacti Device', 'mactrack')
	];

	$rows_selector = [
		-1   => __('Default', 'mactrack'),
		10   => '10',
		15   => '15',
		20   => '20',
		30   => '30',
		50   => '50',
		100  => '100',
		500  => '500',
		1000 => '1000',
		-2   => __('All', 'mactrack')
	];

	$mactrack_poller_frequencies = [
		'disabled' => __('Disabled', 'mactrack'),
		'5'        => __('Every %d Minutes', 5, 'mactrack'),
		'10'       => __('Every %d Minutes', 10, 'mactrack'),
		'15'       => __('Every %d Minutes', 15, 'mactrack'),
		'20'       => __('Every %d Minutes', 20, 'mactrack'),
		'30'       => __('Every %d Minutes', 30, 'mactrack'),
		'60'       => __('Every %d Hour', 1, 'mactrack'),
		'120'      => __('Every %d Hours', 2, 'mactrack'),
		'240'      => __('Every %d Hours', 4, 'mactrack'),
		'480'      => __('Every %d Hours', 8, 'mactrack'),
		'720'      => __('Every %d Hours', 12, 'mactrack'),
		'1440'     => __('Every Day', 'mactrack')
	];

	$mactrack_data_retention = [
		'3'   => __('%d Days', 3, 'mactrack'),
		'7'   => __('%d Days', 7, 'mactrack'),
		'10'  => __('%d Days', 10, 'mactrack'),
		'14'  => __('%d Days', 14, 'mactrack'),
		'20'  => __('%d Days', 20, 'mactrack'),
		'30'  => __('%d Month', 1, 'mactrack'),
		'60'  => __('%d Months', 2, 'mactrack'),
		'120' => __('%d Months', 4, 'mactrack'),
		'240' => __('%d Months', 8, 'mactrack'),
		'365' => __('%d Year', 1, 'mactrack')
	];

	$mactrack_macauth_frequencies = [
		'disabled' => __('Disabled', 'mactrack'),
		'0'        => __('On Scan Completion', 'mactrack'),
		'720'      => __('Every %d Hours', 12),
		'1440'     => __('Every Day', 'mactrack'),
		'2880'     => __('Every %d Days', 2),
		'10080'    => __('Every Week', 'mactrack')
	];

	$menu2 =  [];

	foreach ($menu as $temp => $temp2) {
		$menu2[$temp] = $temp2;

		if ($temp == __('Management')) {
			$menu2[__('Mactrack', 'mactrack')]['plugins/mactrack/mactrack_sites.php']               = __('Sites', 'mactrack');
			$menu2[__('Mactrack', 'mactrack')]['plugins/mactrack/mactrack_devices.php']             = __('Devices', 'mactrack');
			$menu2[__('Mactrack', 'mactrack')]['plugins/mactrack/mactrack_snmp.php']                = __('SNMP Options', 'mactrack');
			$menu2[__('Mactrack', 'mactrack')]['plugins/mactrack/mactrack_device_types.php']        = __('Device Types', 'mactrack');
			$menu2[__('Mactrack', 'mactrack')]['plugins/mactrack/mactrack_vendormacs.php']          = __('Vendor Macs', 'mactrack');
			$menu2[__('Mactrack Tools', 'mactrack')]['plugins/mactrack/mactrack_macwatch.php']      = __('Mac Watch', 'mactrack');
			$menu2[__('Mactrack Tools', 'mactrack')]['plugins/mactrack/mactrack_macauth.php']       = __('Mac Authorizations', 'mactrack');
			$menu2[__('Mactrack Tools', 'mactrack')]['plugins/mactrack/mactrack_utilities.php']     = __('Tracking Utilities', 'mactrack');
		}
	}
	$menu = $menu2;

	if (cacti_version_compare(CACTI_VERSION, '1.2', '<')) {
		$menu_glyphs[__('Mactrack', 'mactrack')] = 'fa fa-shield';
	} else {
		$menu_glyphs[__('Mactrack', 'mactrack')] = 'fa fa-shield-alt';
	}
	$menu_glyphs[__('Mactrack Tools', 'mactrack')] = 'fa fa-bullhorn';
}

/**
 * Populates the field definition arrays for all of this plugin's
 * add/edit forms (device types, devices, sites, SNMP option sets and
 * items, MAC watch, MAC auth). Registered as the 'config_form' Cacti
 * hook.
 *
 * @return void
 *
 * @global array $fields_mactrack_device_type_edit The device type edit
 *                                                form's field
 *                                                definitions;
 *                                                populated here.
 * @global array $fields_mactrack_device_edit      The device edit
 *                                                form's field
 *                                                definitions;
 *                                                populated here.
 * @global array $fields_mactrack_site_edit        The site edit form's
 *                                                field definitions;
 *                                                populated here.
 * @global array $fields_mactrack_snmp_edit        The SNMP option set
 *                                                edit form's field
 *                                                definitions;
 *                                                populated here.
 * @global array $fields_mactrack_snmp_item        The SNMP item field
 *                                                definitions;
 *                                                populated here.
 * @global array $fields_mactrack_snmp_item_edit   The SNMP item edit
 *                                                form's field
 *                                                definitions;
 *                                                populated here.
 * @global array $mactrack_device_types            Device type option
 *                                                list, used to build
 *                                                the device type
 *                                                dropdown.
 * @global array $snmp_versions                    SNMP version option
 *                                                list, used by SNMP-
 *                                                related fields.
 * @global array $fields_mactrack_macw_edit        The MAC watch edit
 *                                                form's field
 *                                                definitions;
 *                                                populated here.
 * @global array $fields_mactrack_maca_edit        The MAC auth edit
 *                                                form's field
 *                                                definitions;
 *                                                populated here.
 * @global array $snmp_priv_protocols              SNMP privacy
 *                                                protocol option list,
 *                                                used by SNMP v3
 *                                                fields.
 * @global array $snmp_auth_protocols              SNMP auth protocol
 *                                                option list, used by
 *                                                SNMP v3 fields.
 */
function mactrack_config_form(): void {
	global $fields_mactrack_device_type_edit, $fields_mactrack_device_edit, $fields_mactrack_site_edit;
	global $fields_mactrack_snmp_edit, $fields_mactrack_snmp_item, $fields_mactrack_snmp_item_edit;
	global $mactrack_device_types, $snmp_versions, $fields_mactrack_macw_edit, $fields_mactrack_maca_edit;
	global $snmp_priv_protocols, $snmp_auth_protocols;

	// file: mactrack_device_types.php, action: edit
	$fields_mactrack_device_type_edit = [
	'spacer0' => [
		'method'        => 'spacer',
		'friendly_name' => __('Device Scanning Function Options', 'mactrack')
		],
	'description' => [
		'method'        => 'textbox',
		'friendly_name' => __('Description', 'mactrack'),
		'description'   => __('Give this device type a meaningful description.', 'mactrack'),
		'value'         => '|arg1:description|',
		'max_length'    => '250'
		],
	'vendor' => [
		'method'        => 'textbox',
		'friendly_name' => __('Vendor', 'mactrack'),
		'description'   => __('Fill in the name for the vendor of this device type.', 'mactrack'),
		'value'         => '|arg1:vendor|',
		'max_length'    => '250'
		],
	'device_type' => [
		'method'        => 'drop_array',
		'friendly_name' => __('Device Type', 'mactrack'),
		'description'   => __('Choose the type of device.', 'mactrack'),
		'value'         => '|arg1:device_type|',
		'default'       => 1,
		'array'         => $mactrack_device_types
		],
	'sysDescr_match' => [
		'method'        => 'textbox',
		'friendly_name' => __('System Description Match', 'mactrack'),
		'description'   => __('Provide key information to help Mactrack detect the type of device.  The wildcard character is the \'&#42;\' sign.', 'mactrack'),
		'value'         => '|arg1:sysDescr_match|',
		'max_length'    => '250'
		],
	'sysObjectID_match' => [
		'method'        => 'textbox',
		'friendly_name' => __('Vendor SNMP Object ID Match', 'mactrack'),
		'description'   => __('Provide key information to help Mactrack detect the type of device.  The wildcard character is the \'&#42;\' sign.', 'mactrack'),
		'value'         => '|arg1:sysObjectID_match|',
		'max_length'    => '250'
		],
	'scanning_function' => [
		'method'        => 'drop_sql',
		'friendly_name' => __('MAC Address Scanning Function', 'mactrack'),
		'description'   => __('Mactrack scanning function to call in order to obtain and store port details.  The function name is all that is required.  The following four parameters are assumed and will always be appended: \'my_function($site, &$device, $lowport, $highport)\'.  There is no function required for a pure router.', 'mactrack'),
		'value'         => '|arg1:scanning_function|',
		'default'       => 0,
		'none_value'    => __('None', 'mactrack'),
		'sql'           => 'select scanning_function as id, scanning_function as name from mac_track_scanning_functions where type="1" order by scanning_function'
		],
	'ip_scanning_function' => [
		'method'        => 'drop_sql',
		'friendly_name' => __('IP Address Scanning Function', 'mactrack'),
		'description'   => __('Mactrack scanning function specific to Layer3 devices that track IP Addresses.', 'mactrack'),
		'value'         => '|arg1:ip_scanning_function|',
		'default'       => 0,
		'none_value'    => __('None', 'mactrack'),
		'sql'           => 'SELECT scanning_function AS id, scanning_function AS name FROM mac_track_scanning_functions WHERE type="2" ORDER BY scanning_function'
		],
	'dot1x_scanning_function' => [
		'method'        => 'drop_sql',
		'friendly_name' => __('802.1x Scanning Function', 'mactrack'),
		'description'   => __('Mactrack scanning function specific to Switches with dot1x enabled.', 'mactrack'),
		'value'         => '|arg1:dot1x_scanning_function|',
		'default'       => '',
		'none_value'    => __('None', 'mactrack'),
		'sql'           => 'SELECT scanning_function AS id, scanning_function AS name FROM mac_track_scanning_functions WHERE type="3" ORDER BY scanning_function'
		],
	'serial_number_oid' => [
		'method'        => 'textbox',
		'friendly_name' => __('Serial Number Base OID', 'mactrack'),
		'description'   => __('The SNMP OID used to obtain this device types serial number to be stored in the Mactrack Asset Information table.', 'mactrack'),
		'value'         => '|arg1:serial_number_oid|',
		'max_length'    => '100',
		'default'       => ''
		],
	'serial_number_oid_type' => [
		'method'        => 'drop_array',
		'friendly_name' => __('Serial Number Collection Method', 'mactrack'),
		'description'   => __('How is the serial number collected for this OID.  If \'SNMP Walk\', we assume multiple serial numbers.  If \'Get\', it will be only one..', 'mactrack'),
		'value'         => '|arg1:serial_number_oid_method|',
		'default'       => 'get',
		'array'         => ['get' => __('SNMP Get', 'mactrack'), 'walk' => __('SNMP Walk', 'mactrack')]
		],
	'lowPort' => [
		'method'        => 'textbox',
		'friendly_name' => __('Low User Port Number', 'mactrack'),
		'description'   => __('Provide the low user port number on this switch.  Leave 0 to allow the system to calculate it.', 'mactrack'),
		'value'         => '|arg1:lowPort|',
		'default'       => read_config_option('mt_port_lowPort'),
		'max_length'    => '100',
		'size'          => '10'
		],
	'highPort' => [
		'method'        => 'textbox',
		'friendly_name' => __('High User Port Number', 'mactrack'),
		'description'   => __('Provide the low user port number on this switch.  Leave 0 to allow the system to calculate it.', 'mactrack'),
		'value'         => '|arg1:highPort|',
		'default'       => read_config_option('mt_port_highPort'),
		'max_length'    => '100',
		'size'          => '10'
		],
	'disabled' => [
		'method'        => 'checkbox',
		'friendly_name' => __('Disabled', 'mactrack'),
		'description'   => __('Disabled device type is not used.', 'mactrack'),
		'value'         => '|arg1:disabled|',
		'default'       => ''
		],
	'device_type_id' => [
		'method' => 'hidden_zero',
		'value'  => '|arg1:device_type_id|'
		],
	'_device_type_id' => [
		'method' => 'hidden_zero',
		'value'  => '|arg1:device_type_id|'
		],
	'save_component_device_type' => [
		'method' => 'hidden',
		'value'  => '1'
		]
	];

	// file: mactrack_snmp.php, action: edit
	$fields_mactrack_snmp_edit = [
	'name' => [
		'method'        => 'textbox',
		'friendly_name' => __('Name', 'mactrack'),
		'description'   => __('Fill in the name of this SNMP option set.', 'mactrack'),
		'value'         => '|arg1:name|',
		'default'       => '',
		'max_length'    => '100',
		'size'          => '40'
		],
	];

	// file: mactrack_snmp.php, action: item_edit
	$fields_mactrack_snmp_item = [
	'snmp_version' => [
		'method'        => 'drop_array',
		'friendly_name' => __('SNMP Version', 'mactrack'),
		'description'   => __('Choose the SNMP version for this host.', 'mactrack'),
		'value'         => '|arg1:snmp_version|',
		'default'       => read_config_option('mt_snmp_ver'),
		'array'         => $snmp_versions
		],
	'snmp_readstring' => [
		'method'        => 'textbox',
		'friendly_name' => __('SNMP Community String', 'mactrack'),
		'description'   => __('Fill in the SNMP read community for this device.', 'mactrack'),
		'value'         => '|arg1:snmp_readstring|',
		'default'       => read_config_option('mt_snmp_community'),
		'max_length'    => '100',
		'size'          => '20'
		],
	'snmp_port' => [
		'method'        => 'textbox',
		'friendly_name' => __('SNMP Port', 'mactrack'),
		'description'   => __('The UDP/TCP Port to poll the SNMP agent on.', 'mactrack'),
		'value'         => '|arg1:snmp_port|',
		'max_length'    => '8',
		'default'       => read_config_option('mt_snmp_port'),
		'size'          => '10'
		],
	'snmp_timeout' => [
		'method'        => 'textbox',
		'friendly_name' => __('SNMP Timeout', 'mactrack'),
		'description'   => __('The maximum number of milliseconds Cacti will wait for an SNMP response (does not work with php-snmp support).', 'mactrack'),
		'value'         => '|arg1:snmp_timeout|',
		'max_length'    => '8',
		'default'       => read_config_option('mt_snmp_timeout'),
		'size'          => '10'
		],
	'snmp_retries' => [
		'method'        => 'textbox',
		'friendly_name' => __('SNMP Retries', 'mactrack'),
		'description'   => __('The maximum number of attempts to reach a device via an SNMP readstring prior to giving up.', 'mactrack'),
		'value'         => '|arg1:snmp_retries|',
		'max_length'    => '8',
		'default'       => read_config_option('mt_snmp_retries'),
		'size'          => '10'
		],
	'max_oids' => [
		'method'        => 'textbox',
		'friendly_name' => __('Maximum OID\'s Per Get Request', 'mactrack'),
		'description'   => __('Specified the number of OID\'s that can be obtained in a single SNMP Get request.', 'mactrack'),
		'value'         => '|arg1:max_oids|',
		'max_length'    => '8',
		'default'       => read_config_option('max_get_size'),
		'size'          => '15'
		],
	'snmp_username' => [
		'method'        => 'textbox',
		'friendly_name' => __('SNMP Username (v3)', 'mactrack'),
		'description'   => __('SNMP v3 username for this device.', 'mactrack'),
		'value'         => '|arg1:snmp_username|',
		'default'       => read_config_option('snmp_username'),
		'max_length'    => '50',
		'size'          => '15'
		],
	'snmp_password' => [
		'method'        => 'textbox_password',
		'friendly_name' => __('SNMP Password (v3)', 'mactrack'),
		'description'   => __('SNMP v3 password for this device.', 'mactrack'),
		'value'         => '|arg1:snmp_password|',
		'default'       => read_config_option('snmp_password'),
		'max_length'    => '50',
		'size'          => '15'
		],
	'snmp_auth_protocol' => [
		'method'        => 'drop_array',
		'friendly_name' => __('SNMP Auth Protocol (v3)', 'mactrack'),
		'description'   => __('Choose the SNMPv3 Authorization Protocol.', 'mactrack'),
		'value'         => '|arg1:snmp_auth_protocol|',
		'default'       => read_config_option('snmp_auth_protocol'),
		'array'         => $snmp_auth_protocols,
		],
	'snmp_priv_passphrase' => [
		'method'        => 'textbox',
		'friendly_name' => __('SNMP Privacy Passphrase (v3)', 'mactrack'),
		'description'   => __('Choose the SNMPv3 Privacy Passphrase.', 'mactrack'),
		'value'         => '|arg1:snmp_priv_passphrase|',
		'default'       => read_config_option('snmp_priv_passphrase'),
		'max_length'    => '200',
		'size'          => '40'
		],
	'snmp_priv_protocol' => [
		'method'        => 'drop_array',
		'friendly_name' => __('SNMP Privacy Protocol (v3)', 'mactrack'),
		'description'   => __('Choose the SNMPv3 Privacy Protocol.', 'mactrack'),
		'value'         => '|arg1:snmp_priv_protocol|',
		'default'       => read_config_option('snmp_priv_protocol'),
		'array'         => $snmp_priv_protocols,
		],
	'snmp_context' => [
		'method'        => 'textbox',
		'friendly_name' => __('SNMP Context (v3)', 'mactrack'),
		'description'   => __('Enter the SNMP v3 Context to use for this device.', 'mactrack'),
		'value'         => '|arg1:snmp_context|',
		'default'       => '',
		'max_length'    => '64',
		'size'          => '40'
		],
	'snmp_engine_id' => [
		'method'        => 'textbox',
		'friendly_name' => __('SNMP Engine ID (v3)', 'mactrack'),
		'description'   => __('Enter the SNMP v3 Engine ID to use for this device.', 'mactrack'),
		'value'         => '|arg1:snmp_engine_id|',
		'default'       => '',
		'max_length'    => '64',
		'size'          => '40'
		],
	];

	// file: mactrack_devices.php, action: edit
	$fields_mactrack_device_edit = [
	'spacer0' => [
		'method'        => 'spacer',
		'friendly_name' => __('General Device Settings', 'mactrack')
		],
	'device_name' => [
		'method'        => 'textbox',
		'friendly_name' => __('Device Name', 'mactrack'),
		'description'   => __('Give this device a meaningful name.', 'mactrack'),
		'value'         => '|arg1:device_name|',
		'max_length'    => '250'
		],
	'hostname' => [
		'method'        => 'textbox',
		'friendly_name' => __('Hostname', 'mactrack'),
		'description'   => __('Fill in the fully qualified hostname for this device.', 'mactrack'),
		'value'         => '|arg1:hostname|',
		'max_length'    => '250'
		],
	'host_id' => [
		'friendly_name' => __('Related Cacti Host', 'mactrack'),
		'description'   => __('Given Mactrack Host is connected to this Cacti Host.', 'mactrack'),
		// 'method' => 'view',
		'method'     => 'drop_sql',
		'value'      => '|arg1:host_id|',
		'none_value' => __('None', 'mactrack'),
		'sql'        => 'select id,CONCAT_WS("",description," (",hostname,")") as name from host order by description,hostname'
		],
	'device_type_id' => [
		'method'        => 'drop_sql',
		'friendly_name' => 'Device Type',
		'description'   => 'Choose the type of device.',
		'value'         => '|arg1:device_type_id|',
		'default'       => 0,
		'none_value'    => 'Not Detected',
		'sql'           => 'select device_type_id as id,description as name from mac_track_device_types order by description'
		],
	'scan_type' => [
		'method'        => 'drop_array',
		'friendly_name' => __('Scan Type', 'mactrack'),
		'description'   => __('Choose the scan type you wish to perform on this device.', 'mactrack'),
		'value'         => '|arg1:scan_type|',
		'default'       => 1,
		'array'         => $mactrack_device_types
		],
	'site_id' => [
		'method'        => 'drop_sql',
		'friendly_name' => __('Site Name', 'mactrack'),
		'description'   => __('Choose the site to associate with this device.', 'mactrack'),
		'value'         => '|arg1:site_id|',
		'none_value'    => __('None', 'mactrack'),
		'sql'           => 'select site_id as id,site_name as name from mac_track_sites order by name'
		],
	'notes' => [
		'method'        => 'textarea',
		'friendly_name' => __('Device Notes', 'mactrack'),
		'description'   => __('This field value is useful to save general information about a specific device.', 'mactrack'),
		'class'         => 'textAreaNotes',
		'textarea_rows' => '3',
		'textarea_cols' => '80',
		'value'         => '|arg1:notes|',
		'max_length'    => '255'
		],
	'disabled' => [
		'method'        => 'checkbox',
		'friendly_name' => __('Disable Device', 'mactrack'),
		'description'   => __('Check this box to disable all checks for this host.', 'mactrack'),
		'value'         => '|arg1:disabled|',
		'default'       => '',
		'form_id'       => false
		],
	'spacer1' => [
		'method'        => 'spacer',
		'friendly_name' => __('Switch/Hub, Switch/Router Settings', 'mactrack')
		],
	'ignorePorts' => [
		'method'        => 'textarea',
		'friendly_name' => __('Ports to Ignore', 'mactrack'),
		'description'   => __('Provide a list of ports on a specific switch/hub whose MAC results should be ignored.  Ports such as link/trunk ports that can not be distinguished from other user ports are examples.  Each port number must be separated by a colon, pipe, or a space \':\', \'|\', \' \'.  For example, \'Fa0/1: Fa1/23\' or \'Fa0/1 Fa1/23\' would be acceptable for some manufacturers switch types.', 'mactrack'),
		'value'         => '|arg1:ignorePorts|',
		'default'       => '',
		'class'         => 'textAreaNotes',
		'textarea_rows' => '3',
		'textarea_cols' => '80',
		'max_length'    => '255'
		],
	'scan_trunk_port' => [
		'method'        => 'textarea',
		'friendly_name' => 'Trunk Ports to Scan',
		'description'   => 'A comma delimited list of Port Number to be scanned.  Some VMware network port will be configured with 802.1Q',
		'value'         => '|arg1:scan_trunk_port|',
		'default'       => '',
		'class'         => 'textAreaNotes',
		'textarea_rows' => '3',
		'textarea_cols' => '80',
		'max_length'    => '255'
		],
	'spacer2' => [
		'method'        => 'spacer',
		'friendly_name' => __('SNMP Options', 'mactrack')
		],
	'snmp_options' => [
		'method'        => 'drop_sql',
		'friendly_name' => __('SNMP Options', 'mactrack'),
		'description'   => __('You can use specific SNMP settings or select SNMP set. In the second case, mactrack tries to find correct settings from SNMP set', 'mactrack'),
		'value'         => '|arg1:snmp_options|',
		'none_value'    => __('None', 'mactrack'),
		'sql'           => 'select * from mac_track_snmp order by name'
		],
	'snmp_readstrings' => [
		'method'        => 'view',
		'friendly_name' => __('Read Strings', 'mactrack'),
		'description'   => __('<strong>DEPRECATED:</strong> SNMP community strings', 'mactrack'),
		'value'         => '|arg1:snmp_readstrings|',
		],
	'spacer3' => [
		'method'        => 'spacer',
		'friendly_name' => __('Specific SNMP Settings', 'mactrack')
		],
	];

	$fields_mactrack_device_edit += $fields_mactrack_snmp_item;

	$fields_mactrack_device_edit += [
	'spacer4' => [
		'method'        => 'spacer',
		'friendly_name' => __('Connectivity Options', 'mactrack')
		],
	'term_type' => [
		'method'        => 'drop_array',
		'friendly_name' => __('Terminal Type', 'mactrack'),
		'description'   => __('Choose the terminal type that you use to connect to this device.', 'mactrack'),
		'value'         => '|arg1:term_type|',
		'default'       => 1,
		'array'         => [
			0 => __('None', 'mactrack'),
			1 => __('Telnet', 'mactrack'),
			2 => __('SSH', 'mactrack'),
			3 => __('HTTP', 'mactrack'),
			4 => __('HTTPS', 'mactrack')]
		],
	'user_name' => [
		'method'        => 'textbox',
		'friendly_name' => __('User Name', 'mactrack'),
		'description'   => __('The user name to be used for your custom authentication method.  Examples include SSH, RSH, HTML, etc.', 'mactrack'),
		'value'         => '|arg1:user_name|',
		'default'       => '',
		'max_length'    => '40',
		'size'          => '20'
		],
	'user_password' => [
		'method'        => 'textbox_password',
		'friendly_name' => __('Password', 'mactrack'),
		'description'   => __('The password to be used for your custom authentication.', 'mactrack'),
		'value'         => '|arg1:user_password|',
		'default'       => '',
		'max_length'    => '40',
		'size'          => '20'
		],
	'private_key_path' => [
		'method'        => 'filepath',
		'friendly_name' => __('Private Key Path', 'mactrack'),
		'description'   => __('The path to the private key used for SSH authentication.', 'mactrack'),
		'value'         => '|arg1:private_key_path|',
		'default'       => '',
		'max_length'    => '128',
		'size'          => '40'
		],
	'device_id' => [
		'method' => 'hidden_zero',
		'value'  => '|arg1:device_id|'
		],
	'_device_id' => [
		'method' => 'hidden_zero',
		'value'  => '|arg1:device_id|'
		],
	'save_component_device' => [
		'method' => 'hidden',
		'value'  => '1'
		]
	];

	// file: mactrack_snmp.php, action: item_edit
	$fields_mactrack_snmp_item_edit = $fields_mactrack_snmp_item + [
	'sequence' => [
		'method'        => 'view',
		'friendly_name' => __('Sequence', 'mactrack'),
		'description'   => __('Sequence of Item.', 'mactrack'),
		'value'         => '|arg1:sequence|'],
	];

	// file: mactrack_sites.php, action: edit
	$fields_mactrack_site_edit = [
	'spacer0' => [
		'method'        => 'spacer',
		'friendly_name' => __('General Site Settings', 'mactrack')
		],
	'site_name' => [
		'method'        => 'textbox',
		'friendly_name' => __('Site Name', 'mactrack'),
		'description'   => __('Please enter a reasonable name for this site.', 'mactrack'),
		'value'         => '|arg1:site_name|',
		'size'          => '70',
		'max_length'    => '250'
		],
	'customer_contact' => [
		'method'        => 'textbox',
		'friendly_name' => __('Primary Customer Contact', 'mactrack'),
		'description'   => __('The principal customer contact name and number for this site.', 'mactrack'),
		'value'         => '|arg1:customer_contact|',
		'size'          => '70',
		'max_length'    => '150'
		],
	'netops_contact' => [
		'method'        => 'textbox',
		'friendly_name' => __('NetOps Contact', 'mactrack'),
		'description'   => __('Please principal network support contact name and number for this site.', 'mactrack'),
		'value'         => '|arg1:netops_contact|',
		'size'          => '70',
		'max_length'    => '150'
		],
	'facilities_contact' => [
		'method'        => 'textbox',
		'friendly_name' => __('Facilities Contact', 'mactrack'),
		'description'   => __('Please principal facilities/security contact name and number for this site.', 'mactrack'),
		'value'         => '|arg1:facilities_contact|',
		'size'          => '70',
		'max_length'    => '150'
		],
	'site_info' => [
		'method'        => 'textarea',
		'friendly_name' => __('Site Information', 'mactrack'),
		'class'         => 'textAreaNotes',
		'textarea_rows' => '3',
		'textarea_cols' => '80',
		'description'   => __('Provide any site-specific information, in free form, that allows you to better manage this location.', 'mactrack'),
		'value'         => '|arg1:site_info|',
		'max_length'    => '255'
		],
	'skip_vlans' => [
		'method'        => 'textarea',
		'friendly_name' => 'VLAN ID to Skipped Scan',
		'class'         => 'textAreaNotes',
		'textarea_rows' => '5',
		'textarea_cols' => '80',
		'description'   => 'A comma delimited list of VLAN ID always forced to be skipped scanning.',
		'value'         => '|arg1:skip_vlans|',
		'max_length'    => '1024'
		],
	'scan_vlans' => [
		'method'        => 'textarea',
		'friendly_name' => 'VLAN ID to Scan',
		'class'         => 'textAreaNotes',
		'textarea_rows' => '5',
		'textarea_cols' => '80',
		'description'   => 'A comma delimited list of VLAN ID to be scanned',
		'value'         => '|arg1:scan_vlans|',
		'max_length'    => '1024'
		],
	'site_id' => [
		'method' => 'hidden_zero',
		'value'  => '|arg1:site_id|'
		],
	'_site_id' => [
		'method' => 'hidden_zero',
		'value'  => '|arg1:site_id|'
		],
	'save_component_site' => [
		'method' => 'hidden',
		'value'  => '1'
		]
	];

	// file: mactrack_macwatch.php, action: edit
	$fields_mactrack_macw_edit = [
	'spacer0' => [
		'method'        => 'spacer',
		'friendly_name' => __('General Mac Address Tracking Settings', 'mactrack')
		],
	'mac_address' => [
		'method'        => 'textbox',
		'friendly_name' => __('MAC Address', 'mactrack'),
		'description'   => __('Please enter the MAC Address to be watched for.', 'mactrack'),
		'value'         => '|arg1:mac_address|',
		'default'       => '',
		'max_length'    => '40'
		],
	'name' => [
		'method'        => 'textbox',
		'friendly_name' => __('MAC Tracking Name/Email Subject', 'mactrack'),
		'description'   => __('Please enter a reasonable name for this MAC Tracking entry.  This information will be in the subject line of your Email', 'mactrack'),
		'value'         => '|arg1:name|',
		'size'          => '70',
		'max_length'    => '250'
		],
	'description' => [
		'friendly_name' => __('MacWatch Default Body', 'mactrack'),
		'description'   => htmlspecialchars(__('The Email body preset for Mactrack MacWatch Emails.  The body can contain any valid html tags.  It also supports replacement tags that will be processed when sending an Email.  Valid tags include <IP>, <MAC>, <TICKET>, <SITENAME>, <DEVICEIP>, <PORTNAME>, <PORTNUMBER>, <DEVICENAME>.', 'mactrack')),
		'method'        => 'textarea',
		'class'         => 'textAreaNotes',
		'value'         => '|arg1:description|',
		'default'       => __('Mac Address <MAC> found at IP Address <IP> for Ticket Number: <TICKET>.<br>The device is located at<br>Site: <SITENAME>, Device <DEVICENAME>, IP <DEVICEIP>, Port <PORTNUMBER>, and Port Name <PORTNAME>', 'mactrack'),
		'max_length'    => '512',
		'textarea_rows' => '5',
		'textarea_cols' => '80',
		],
	'ticket_number' => [
		'method'        => 'textbox',
		'friendly_name' => __('Ticket Number', 'mactrack'),
		'description'   => __('Ticket number for cross referencing with your corporate help desk system(s).', 'mactrack'),
		'value'         => '|arg1:ticket_number|',
		'size'          => '70',
		'max_length'    => '150'
		],
	'notify_schedule' => [
		'method'        => 'drop_array',
		'friendly_name' => __('Notification Schedule', 'mactrack'),
		'description'   => __('Choose how often an Email should be generated for this Mac Watch item.', 'mactrack'),
		'value'         => '|arg1:notify_schedule|',
		'default'       => '1',
		'array'         => [
			1    => __('First Occurrence Only', 'mactrack'),
			2    => __('All Occurrences', 'mactrack'),
			60   => __('Every Hour', 'mactrack'),
			240  => __('Every %d Hours', 4, 'mactrack'),
			1800 => __('Every %d Hours', 12, 'mactrack'),
			3600 => __('Every Day', 'mactrack')]
		],
	'email_addresses' => [
		'method'        => 'textbox',
		'friendly_name' => __('Email Addresses', 'mactrack'),
		'description'   => __('Enter a semicolon separated of Email addresses that will be notified where this MAC address is.', 'mactrack'),
		'value'         => '|arg1:email_addresses|',
		'size'          => '90',
		'max_length'    => '255'
		],
	'mac_id' => [
		'method' => 'hidden_zero',
		'value'  => '|arg1:mac_id|'
		],
	'_mac_id' => [
		'method' => 'hidden_zero',
		'value'  => '|arg1:mac_id|'
		],
	'save_component_macw' => [
		'method' => 'hidden',
		'value'  => '1'
		]
	];

	// file: mactrack_macwatch.php, action: edit
	$fields_mactrack_maca_edit = [
	'spacer0' => [
		'method'        => 'spacer',
		'friendly_name' => __('General Mac Address Authorization Settings', 'mactrack')
		],
	'mac_address' => [
		'method'        => 'textbox',
		'friendly_name' => __('MAC Address Match', 'mactrack'),
		'description'   => __('Please enter the MAC Address or Mac Address Match string to be automatically authorized.  If you wish to authorize a group of MAC Addresses, you can use the wildcard character of \'&#37;\' anywhere in the MAC Address.', 'mactrack'),
		'value'         => '|arg1:mac_address|',
		'default'       => '',
		'max_length'    => '40'
		],
	'description' => [
		'method'        => 'textarea',
		'friendly_name' => __('Reason', 'mactrack'),
		'class'         => 'textAreaNotes',
		'description'   => __('Please add a reason for this entry.', 'mactrack'),
		'value'         => '|arg1:description|',
		'textarea_rows' => '4',
		'textarea_cols' => '80'
		],
	'mac_id' => [
		'method' => 'hidden_zero',
		'value'  => '|arg1:mac_id|'
		],
	'_mac_id' => [
		'method' => 'hidden_zero',
		'value'  => '|arg1:mac_id|'
		],
	'save_component_maca' => [
		'method' => 'hidden',
		'value'  => '1'
		]
	];
}

/**
 * Migrates legacy per-device colon-delimited snmp_readstrings values
 * into the newer SNMP option set model: for each distinct combination
 * of read strings/version/port/timeout/retries found across existing
 * devices, creates a new named SNMP option set with one item per read
 * string. Invoked once from mactrack_check_upgrade() and guarded by
 * the mt_convert_readstrings setting so it only runs a single time.
 *
 * @return void
 *
 * @global array $config Cacti global configuration array (declared but
 *                       not used directly here).
 */
function convert_readstrings(): void {
	global $config;

	$sql = 'SELECT DISTINCT ' .
		'snmp_readstrings, ' .
		'snmp_version, ' .
		'snmp_port, ' .
		'snmp_timeout, ' .
		'snmp_retries ' .
		'FROM mac_track_devices';

	$devices = db_fetch_assoc($sql);

	if (cacti_sizeof($devices)) {
		$i = 0;

		foreach ($devices as $device) {
			// create new SNMP Option Set
			unset($save);
			$save['id']   = 0;
			$save['name'] = 'Custom_' . $i++;
			$snmp_id      = sql_save($save, 'mac_track_snmp');

			// add each single option derived from readstrings
			$read_strings = explode(':',$device['snmp_readstrings']);

			if (cacti_sizeof($read_strings)) {
				foreach ($read_strings as $snmp_readstring) {
					unset($save);
					$save['id']						      = 0;
					$save['snmp_id'] 				  = $snmp_id;
					$save['sequence'] 				 = get_sequence('', 'sequence', 'mac_track_snmp_items', 'snmp_id=' . $snmp_id);

					$save['snmp_readstring'] 		     = $snmp_readstring;
					$save['snmp_version'] 			       = $device['snmp_version'];
					$save['snmp_port']				          = $device['snmp_port'];
					$save['snmp_timeout']			        = $device['snmp_timeout'];
					$save['snmp_retries']			        = $device['snmp_retries'];
					$save['snmp_username']			       = '';
					$save['snmp_password']			       = '';
					$save['snmp_auth_protocol']		   = '';
					$save['snmp_priv_passphrase']	  = '';
					$save['snmp_priv_protocol']		   = '';
					$save['snmp_context']			        = '';
					$save['snmp_engine_id']         = '';
					$save['max_oids']				           = '';

					$item_id = sql_save($save, 'mac_track_snmp_items');
				}
			} // each readstring added as SNMP Option item

			// now, let's find all devices, that used this snmp_readstrings
			$sql = 'UPDATE mac_track_devices SET snmp_options=' . $snmp_id .
					" WHERE snmp_readstrings='" . $device['snmp_readstrings'] .
					"' AND snmp_version=" . $device['snmp_version'] .
					' AND snmp_port=' . $device['snmp_port'] .
					' AND snmp_timeout=' . $device['snmp_timeout'] .
					' AND snmp_retries=' . $device['snmp_retries'];

			$ok = db_execute($sql);
		}
	}
	db_execute("REPLACE INTO settings (name,value) VALUES ('mt_convert_readstrings', 'on')");
	// we keep the field:snmp_readstrings in mac_track_devices, it should be deprecated first
	// next mactrack release may delete that field, then
}

/**
 * Removes files and directories that a previous version of this plugin
 * shipped but that have since moved or been deleted, using the tombstone
 * and whitelist lists in manifest.json. Whitelisted (user-data) paths and
 * any VCS metadata (.git*) are never touched; the dev-only tests/ tree is
 * removed. Any path that resolves outside the plugin directory (a tampered
 * manifest.json) is refused, and any file/directory that cannot be removed
 * (e.g. read-only) is reported to the Cacti log. Any top-level entry that is
 * neither expected nor a tombstone nor whitelisted is logged to the Cacti
 * log and left in place. Called on a plugin version change.
 *
 * @return void
 *
 * @global array $config Cacti global configuration array; used to resolve
 *                       the plugin directory.
 */
function mactrack_prune_files(): void {
	global $config;

	$plugin_dir    = $config['base_path'] . '/plugins/mactrack';
	$manifest_path = $plugin_dir . '/manifest.json';

	if (!is_readable($manifest_path)) {
		return;
	}

	$manifest = json_decode((string) file_get_contents($manifest_path), true);

	if (!is_array($manifest)) {
		cacti_log('WARNING: mactrack manifest.json could not be parsed; skipping file prune', false, 'MACTRACK');

		return;
	}

	$tombstones = isset($manifest['tombstones']) && is_array($manifest['tombstones']) ? $manifest['tombstones'] : [];
	$expected   = isset($manifest['expected'])   && is_array($manifest['expected'])   ? $manifest['expected']   : [];
	$whitelist  = isset($manifest['whitelist'])  && is_array($manifest['whitelist'])  ? $manifest['whitelist']  : [];

	$protected = function (string $rel) use ($whitelist): bool {
		if (strncmp($rel, '.git', 4) === 0 || strncmp($rel, '.md', 3) === 0) {
			return true;
		}

		foreach ($whitelist as $entry) {
			$entry = trim((string) $entry, '/');

			if ($entry !== '' && ($rel === $entry
				|| strncmp($rel, $entry . '/', strlen($entry) + 1) === 0
				|| strncmp($entry, $rel . '/', strlen($rel) + 1) === 0)) {
				return true;
			}
		}

		return false;
	};

	// Security: resolve the plugin directory so a tampered manifest.json
	// cannot steer the prune outside of it.
	$plugin_real = realpath($plugin_dir);

	// Remove tombstoned (moved/deleted) paths plus the dev-only tests/
	// tree and the phpunit.xml test configuration.
	$remove   = $tombstones;
	$remove[] = 'tests/';
	$remove[] = 'phpunit.xml';

	foreach ($remove as $rel) {
		$rel = trim((string) $rel, '/');

		if ($rel === '' || $protected($rel)) {
			continue;
		}

		// A tombstone must never contain '.'/'..' segments; a tampered manifest
		// could use them to escape the plugin directory or target its root.
		$segments = explode('/', $rel);

		if (in_array('.', $segments, true) || in_array('..', $segments, true)) {
			cacti_log(sprintf('WARNING: mactrack prune refused to remove %s: path contains a traversal segment (tampered manifest.json?)', $rel), false, 'MACTRACK');

			continue;
		}

		$path = $plugin_dir . '/' . $rel;

		if (!is_link($path) && !file_exists($path)) {
			continue;
		}

		// Refuse any path that, after resolving symlinks and ../ segments,
		// escapes the plugin directory (protects user data from a tampered
		// manifest.json).
		$anchor = is_link($path) ? dirname($path) : $path;
		$real   = realpath($anchor);

		if ($real === false || ($real !== $plugin_real && strncmp($real, $plugin_real . DIRECTORY_SEPARATOR, strlen((string) $plugin_real) + 1) !== 0)) {
			cacti_log(sprintf('WARNING: mactrack prune refused to remove %s: path resolves outside the plugin directory (tampered manifest.json?)', $rel), false, 'MACTRACK');

			continue;
		}

		if (is_dir($path) && !is_link($path)) {
			$removed = mactrack_rmtree($path);
		} else {
			$removed = @unlink($path);
		}

		if (!$removed) {
			cacti_log(sprintf('WARNING: mactrack upgrade could not remove %s (check file/directory permissions)', $rel), false, 'MACTRACK');
		}
	}

	// Surface any top-level entry the manifest does not account for.
	$known = [];

	foreach (array_merge($expected, $tombstones) as $entry) {
		$top = explode('/', trim((string) $entry, '/'))[0];

		if ($top !== '') {
			$known[$top] = true;
		}
	}

	$entries = scandir($plugin_dir);

	foreach (($entries !== false ? $entries : []) as $entry) {
		if ($entry === '.' || $entry === '..' || $entry === 'tests' || $entry === 'phpunit.xml' || $protected($entry) || isset($known[$entry])) {
			continue;
		}

		cacti_log(sprintf('WARNING: mactrack upgrade found a file/directory not described in manifest.json: %s (left in place)', $entry), false, 'MACTRACK');
	}
}

/**
 * Recursively deletes a directory and its contents. Symlinks are removed
 * without being followed. Helper for mactrack_prune_files().
 *
 * @param string $dir Absolute path to the directory to remove.
 *
 * @return bool True if the directory and everything under it was removed;
 *              false if any entry could not be deleted.
 */
function mactrack_rmtree(string $dir): bool {
	$entries = scandir($dir);
	$ok      = true;

	foreach (($entries !== false ? $entries : []) as $entry) {
		if ($entry === '.' || $entry === '..') {
			continue;
		}

		$path = $dir . '/' . $entry;

		if (is_dir($path) && !is_link($path)) {
			if (!mactrack_rmtree($path)) {
				$ok = false;
			}
		} elseif (!@unlink($path)) {
			$ok = false;
		}
	}

	if (!@rmdir($dir)) {
		$ok = false;
	}

	return $ok;
}