extensions:teemip-ip-discovery-collector
Differences
This shows you the differences between two versions of the page.
| Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
| extensions:teemip-ip-discovery-collector [2023/08/07 15:26] – [Revision History] cnaud | extensions:teemip-ip-discovery-collector [2023/09/14 22:37] (current) – removed cnaud | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | {{ icons8-binoculars-48.png}} | ||
| - | ====== IP Discovery - Collector ====== | ||
| - | ---- dataentry summary ---- | ||
| - | name : IP Discovery - Collector | ||
| - | description_wiki | ||
| - | index_hidden | ||
| - | level_hidden | ||
| - | version | ||
| - | release_dt | ||
| - | TeemIp | ||
| - | iTop : 3.x | ||
| - | code : teemip-ip-discovery-collector | ||
| - | localization | ||
| - | state : stable | ||
| - | diffusion_hidden | ||
| - | product_hidden | ||
| - | module-lists_hidden : | ||
| - | keyword_tags | ||
| - | dependencies_s | ||
| - | download_wiki | ||
| - | github_wiki | ||
| - | php-max | ||
| - | ---- | ||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | TeemIp IP Discovery Collector is the standalone application that discovers active IPs on networks based on directives provided by the the TeemIp IP Discovery Extension installed on TeemIp. | ||
| - | |||
| - | < | ||
| - | </ | ||
| - | |||
| - | |||
| - | ===== Revision History ===== | ||
| - | ^ Version | ||
| - | | 3.1.1 | 2023-08-07 | ||
| - | | 3.1.0 | 2023-07-25 | ||
| - | | 3.0.1 | 2022-09-21 | ||
| - | | 0.5.0 | 2020-10-20 | ||
| - | | 0.4.0 | 2019-10-11 | ||
| - | | 0.3.0 | 2019-02-09 | ||
| - | |||
| - | ===== Features ===== | ||
| - | |||
| - | Reminder: TeemIp IP Discovery provides a solution to TeemIp administrators to discover or scan their IP networks and to document within TeemIp the results of these discoveries and scans. | ||
| - | |||
| - | The solution is made of 2 components: | ||
| - | * a [[extensions: | ||
| - | * a [[extensions: | ||
| - | |||
| - | {{ ipdiscoveryprinciples3x.png | ||
| - | |||
| - | The IP Discovery Application is a standalone PHP software that extends iTop's collectors principles. It has been built on top of [[https:// | ||
| - | * the list of subnets they have to discover, | ||
| - | * the global discovery method they need to use (ping, IP lookup, port scan), | ||
| - | * the restrictions that each subnet may impose (on ping, IP lookup, port scan). | ||
| - | |||
| - | At regular interval (defined by the administrator through a CRON command) the remote collector retrieves in TeemIp the list of networks that it has to discover and, for each of them, the list of IPs already registered. It, then, scans the network, computes | ||
| - | * New discovered IPs are created, | ||
| - | * Ping, IP lookup or scan statuses are updated, | ||
| - | * A few statics on the discovery are documented within each subnet. | ||
| - | |||
| - | <note tip> | ||
| - | Should your network be compartmentalized by different firewalls, the different instances will allow you to bypass the restrictions imposed by the firewalls: limited pings or udp / tcp connections, | ||
| - | </ | ||
| - | |||
| - | ===== Licensing ===== | ||
| - | |||
| - | TeemIp IP Discovery collector is licensed under the terms of the GNU Affero General Public License Version 3 as published by the Free Software Foundation. This gives you legal permission to copy, distribute and/or modify TeemIp IP Discovery collector under certain conditions. Read the ’license.txt’ file in the distribution. TeemIp IP Discovery collector is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE WARRANTY OF DESIGN, MERCHANTABILITY, | ||
| - | |||
| - | ===== Limitations ===== | ||
| - | |||
| - | Discovery of IPv6 networks is not handled at this stage. | ||
| - | |||
| - | ===== Requirements ===== | ||
| - | |||
| - | On the application' | ||
| - | ===== Installation ===== | ||
| - | |||
| - | <note important> | ||
| - | |||
| - | Expand the content of the zip archive in a folder of the server that will run the discovery. | ||
| - | ===== Configuration ===== | ||
| - | |||
| - | |||
| - | Like every iTop collector, the configuration of the application is based on the '' | ||
| - | |||
| - | <code xml> | ||
| - | <?xml version=" | ||
| - | <!-- Parameters specific to the discovery instance. --> | ||
| - | < | ||
| - | <!-- TeemIp Application --> | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | |||
| - | <!-- Class collection sequence --> | ||
| - | < | ||
| - | <!-- IPv4 addresses --> | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | </ | ||
| - | <!-- IPv4 subnets --> | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | </ | ||
| - | <!-- IP applications --> | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | </ | ||
| - | </ | ||
| - | | ||
| - | <!-- Synchronization parameters --> | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | <!-- IP Discovery Application UUID --> | ||
| - | < | ||
| - | <!-- Name of synchronization data sources --> | ||
| - | < | ||
| - | < | ||
| - | </ | ||
| - | |||
| - | <!-- IP Addresses Parameters --> | ||
| - | < | ||
| - | < | ||
| - | | ||
| - | <!-- Discovery functions --> | ||
| - | < | ||
| - | < | ||
| - | |||
| - | </ | ||
| - | </ | ||
| - | |||
| - | |||
| - | ^ Parameter ^ Meaning ^ Sample value ^ | ||
| - | | itop_url | URL to the TeemIp Application. | < | ||
| - | | itop_login | Login (user account) for connecting to TeemIp. Must have admin rights for executing the data synchro. | admin | | ||
| - | | itop_password | Password for the iTop account. | admin_pwd | | ||
| - | | collectors_launch_sequence | List of collectors to run | N/A | | ||
| - | | collector | Details for a collector class | N/A | | ||
| - | | name | Name of the collector class | TeemIpDiscoveryIPv4Collector | | ||
| - | | | ||
| - | | rank | Order of the collect amongst allother collectors | 1 | | ||
| - | | contact_to_notify | The email address of an existing contact in TeemIp to be notified of the results of the synchronization. | john.doe@demo.com | | ||
| - | | discovery_application_uuid | String that uniquely identifies the remote the IP Discovery Application in TeemIp. The string is automatically created at creation time of the IP Discovery object| FFF3_60D8_FEE6_520D | | ||
| - | | ipv4_synchro_name | Name of the data IPv4 synchro that the discovery application will create in TeemIp. By default, the UUID will be appended to that string. | TeemIp IPv4 Discovery | | ||
| - | |subnetv4_synchro_name | Name of the IPv4 subnet data synchro that the discovery application will create in TeemIp. By default, the UUID will be appended to that string.| TeemIp IPv4 Subnet Discovery | | ||
| - | | ip_default_status | Status of IPs when create by the discovery application. Possible values: allocated, released, reserved, unassigned | unassigned | | ||
| - | | ip_default_view | String that defines the default view to be set on discovered IPs (if relevant) | "" | ||
| - | | ping_absolute_path | Absolute path of the ping tool | /bin/ | | ||
| - | | dig_absolute_path | Absolute path of the dig tool | /usr/bin/ | | ||
| - | |||
| - | |||
| - | <note tip>The [[https:// | ||
| - | |||
| - | <note warning> | ||
| - | |||
| - | ===== Run the discovery ===== | ||
| - | |||
| - | To launch the IP discovery and synchronization with TeemIp, run the following command (from the root directory where the IP Discovery application is installed): | ||
| - | |||
| - | < | ||
| - | php exec.php | ||
| - | </ | ||
| - | |||
| - | The following (optional) command line options are available: | ||
| - | |||
| - | ^ Option ^ Meaning ^ default value ^ | ||
| - | | < | ||
| - | | < | ||
| - | | < | ||
| - | | < | ||
| - | | < | ||
| - | | < | ||
| - | | < | ||
| - | | < | ||
| - | |||
| - | Once invoked through the command line, the discovery application will: | ||
| - | * Create its collection plan by connecting to TeemIp and retrieve: | ||
| - | * The main discovery parameters to use, | ||
| - | * The list of subnets to discover and their specific settings (with regard the ping, ip lookup and scan functions), | ||
| - | * The list of IPs already configured in TeemIp and their attributes, | ||
| - | * Connect to TeemIp to create the related Synchronization Data Sources (or check their definition if they already exist and update them if needed) | ||
| - | * Ping and / or look up and / or scan all subnets' | ||
| - | * Upload the collected data into TeemIp, | ||
| - | * Synchronize the collected data with the existing TeemIp IPs, | ||
| - | * Update the discovered subnets with their respective discovery durations, | ||
| - | * Update statistics of discovery application. | ||
| - | |||
| - | ==== Scheduling ==== | ||
| - | |||
| - | Once you've run the IP Discovery interactively, | ||
| - | |||
| - | The IP Discovery application does not provide any specific scheduling mechanism, but the simple command line '' | ||
| - | |||
| - | <note tip>For optimal results, don't forget to adjust the configuration parameter '' | ||
| - | |||
| - | ==== Discovery functions ==== | ||
| - | |||
| - | The IP Discovery application discovers networks through 3 standard network functions: ping, IP lookup and port scanning, each of them being individually activated for the applications. Furthermore, | ||
| - | |||
| - | **// | ||
| - | |||
| - | This is the standard and well known command based on icmp request. It is called with the following parameters: | ||
| - | |||
| - | ^ Parameter ^ Defined in ^ Default value ^ | ||
| - | | ping_absolute_path | / | ||
| - | | Ping timeout (s) | IP Discovery Application in TeemIp | 1 s | | ||
| - | |||
| - | The command is invoked through the exec PHP function. | ||
| - | |||
| - | < | ||
| - | |||
| - | For instance: | ||
| - | |||
| - | / | ||
| - | |||
| - | |||
| - | **//IP Lookup//** | ||
| - | |||
| - | This function checks if an entry exists in the DNS space for the IPs. It relies on the dig command and sends reverse lookups to 1 or 2 DNS servers. It is called with the following parameters: | ||
| - | |||
| - | ^ Parameter ^ Defined in ^ Default value ^ | ||
| - | | dig_absolute_path | / | ||
| - | | DNS server #1 |IP Discovery Application in TeemIp - Can be a FQDN or an IP | < | ||
| - | | DNS server #1 |IP Discovery Application in TeemIp - Can be a FQDN or an IP | < | ||
| - | |||
| - | The command is invoked through the exec PHP function. | ||
| - | |||
| - | < | ||
| - | |||
| - | For instance: | ||
| - | |||
| - | / | ||
| - | or | ||
| - | dig -x 10.11.12.13 @mydnsserver.com | ||
| - | |||
| - | If no DNS server is provided, then the command is invoked without the @ and dig will rely on the DNS servers defined in the / | ||
| - | |||
| - | When 2 DNS servers are given then: | ||
| - | * If the first one provides us with a response, no further lookup is done for the IP. | ||
| - | * If the first one doesn' | ||
| - | |||
| - | |||
| - | **//Port scanning// | ||
| - | |||
| - | The function is based on the PHP fsockopen function. The test is done according to the following parameters: | ||
| - | |||
| - | ^ Parameter ^ Defined in ^ Default value ^ | ||
| - | | Port number | IP Discovery Application in TeemIp | none | | ||
| - | | Protocol | IP Discovery Application in TeemIp | none | | ||
| - | | Scan timeout (s) | IP Discovery Application in TeemIp | 1 s | | ||
| - | |||
| - | For both UDP and TCP tests, the scan tries to open a socket on the given port. | ||
| - | * For UDP, we must wait for an answer from the remote host for <scan timeout> seconds before declaring the test as failed. | ||
| - | * For TCP test, answer may come faster if a remote host exists and listen on that port. | ||
| - | |||
| - | If the protocol is set to " | ||
| - | * UDP is tried first. | ||
| - | * If no answered is received, a test is done with TCP. | ||
| - | |||
| - | According to the parameter //Consider “connection refused” as valid//, a scan that fails with error 111 (connection is refused) may be considered as valid from a discovery standpoint. | ||
| - | |||
| - | ===== Synchronize discovery applications, | ||
| - | Discovery results of an IP Discovery Application are fed back to TeemIp through standard synchro data sources. Every IP discovery application will automatically create its own synchro data sources and will use them to push its finding and statistics into TeemIp, systematically, | ||
| - | |||
| - | These synchro data sources can be listed and managed from the Synchronization Data Sources menu under the Admin tools section. As usual with synchro data sources, the Status tab will provide information on every synchronization that occurred between the remote IP Discovery application and TeemIp. | ||
| - | |||
| - | |||
| - | ==== TeemIp Discovery Application ==== | ||
| - | |||
| - | {{ details_synchrodatasource_applicationdiscovery3x.png }} | ||
| - | |||
| - | Default parameters for a given data source are defined in the remote IP Discovery application configuration file. | ||
| - | * The UUID of the application is appended to the name of the synchro data source for an easy identification, | ||
| - | * Statistics on discovery durations are updated. | ||
| - | |||
| - | Reconciliation of the Application is made on the UUID. The following attributes may be affected by this synchro: | ||
| - | |||
| - | ^ Name ^ When ? ^ Comment ^ | ||
| - | | Last discovery date | Creation and update | | | ||
| - | | Duration | Creation and update | | | ||
| - | |||
| - | |||
| - | ==== TeemIp IPv4 Discovery ==== | ||
| - | |||
| - | {{ details_synchrodatasource_ipdiscovery3x.png }} | ||
| - | |||
| - | Default parameters for a given data source are defined in the remote IP Discovery application configuration file. | ||
| - | * The UUID of the application is appended to the name of the synchro data source for an easy identification, | ||
| - | * Discovered IPs that don't already exist in TeemIp are created, | ||
| - | * Already existing IPs are updated, | ||
| - | * No automatic deletion is done. | ||
| - | |||
| - | Reconciliation of IP addresses is done on the Organization and Address attributes. The following attributes may be affected by this synchro: | ||
| - | |||
| - | ^ Name ^ When ? ^ Comment ^ | ||
| - | | Organization | Creation only | | | ||
| - | | Status | Creation only | | | ||
| - | | Address | Creation only | | | ||
| - | | DNS View* | Creation only | If applicable | | ||
| - | | Last discovery date | Creation and update | | | ||
| - | | Responds to ping | Creation and update | | | ||
| - | | Responds to IP lookup| Creation and update | | | ||
| - | | FQDN from IP lookup | Creation and update | | | ||
| - | | Responds to scan | Creation and update | | | ||
| - | |||
| - | |||
| - | <note tip> | ||
| - | The discovery collector automatically detects if the Zone Management extension is installed on the remote application: | ||
| - | * If this is the case: the collector handles the DNS view attribute brought by the extension. | ||
| - | * If this is NOT the case: the DNS view attribute is not managed. | ||
| - | </ | ||
| - | ==== TeemIp IPv4 Subnet Discovery ==== | ||
| - | |||
| - | {{ details_synchrodatasource_subnetdiscovery3x.png }} | ||
| - | |||
| - | Default parameters for a given data source are defined in the remote IP Discovery application configuration file. | ||
| - | * The UUID of the application is appended to the name of the synchro data source for an easy identification, | ||
| - | * Statistics on discovery durations are updated. | ||
| - | |||
| - | Reconciliation of IP subnets is done on the Organization and Subnet IP attributes. The following attributes may be affected by this synchro: | ||
| - | |||
| - | ^ Name ^ When ? ^ | ||
| - | | Last discovery date | Update | | ||
| - | | Ping duration | Update | | ||
| - | | Ping # | Update | | ||
| - | | IP lookup duration | Update | | ||
| - | | IP Lookup # | Update | | ||
| - | | Scan duration | Update | | ||
| - | | Scan # | Update | | ||
extensions/teemip-ip-discovery-collector.1691414781.txt.gz · Last modified: 2023/08/07 15:26 by cnaud