This documentation refers to a previously released version of BMC Discovery.
See the information on this topic for the latest version (11.3) or version 11.2.

The tw_scan_control command line utility enables you to do the following:

  • Perform immediate and scheduled scans of IP addresses or ranges
  • Start and stop Reasoning
  • Disable and enable scheduled scans
  • Remove and update scheduled scans

Recommendation

Use the BMC Discovery user interface to perform the functionality provided by the tw_scan_control command line utility (see Scanning IP addresses or ranges). If you choose to run the utility, read the information in this section to learn its usage and to understand the risks and potential impact on your environment.

 

This page contains the following sections:

The sections describe following topics in detail:

  • Using the tw_scan_control utility—This section contains the general guidelines to use the tw_scan_control utility. 
  • Common options to manage snapshot and scheduled scans—This section contains information about the common options to manage snapshot and scheduled scans, such as starting and stopping discovery and adding discovery runs.
  • Options to manage scheduled scans—This section contains information about the options to manage scheduled scans, such as adding scheduled discovery runs, enabling and disabling scheduled discovery runs, listing scheduled discovery runs, and updating and deleting scheduled discovery runs.
  • Overlapping of scheduled scans and excludes—This section contains information about the expected behavior in the event of overlapping of scheduled scans and excludes.

Using the tw_scan_control utility

To use the utility, type the following command:

tw_scan_control [options] range

where:

  • range is a single entry or a space separated list of IP address information in the following formats:
    • IPv4 address (for example 192.168.1.100).
    • IPv6 address (for example 2001:500:100:1187:203:baff:fe44:91a0).
    • IPv4 range (for example 192.168.1.100-105192.168.1.100/24, or 192.168.1.*).
      If you use the --file option, a range refers to a file that contains IP addresses.
  • options are any of the options described in the following table and the common command line options described in Using command line utilities.

Scanning the following address types is not supported:
• IPv6 link local addresses (prefix fe80::/64)
• IPv6 multicast addresses (prefix ff00::/8)
• IPv6 network prefix (for example fda8:7554:2721:a8b3::/64)
• IPv4 multicast addresses (224.0.0.0 to 239.255.255.255)

In each of the sections below, user examples have been included for your reference. In these examples, the user name is system and the password is not specified on the command line. The utility prompts for the password after you enter the command. Type the commands on a single line; line breaks are provided in the examples to make them easier to read. Note the following:

  • If you want to scan a range of IP addresses listed in a file, make sure that the IP addresses are arranged in a newline separated list.
  • With --enable--disable--remove, and --update=ID you are required to enter the list of corresponding range IDs. You can view the list of range IDs by using the --list and --list-full command line options.

Common options to manage snapshot and scheduled scans

The common command line options are described in Using command line utilities.

By using the common options for snapshot and scheduled scans with the tw_scan_control command line utility, you can perform the following:

Starting and stopping discovery

Use the following common options with the tw_scan_control command line utility to start and stop discovery:

Command Line Option

Description

-s, --start

Starts Reasoning. This is equivalent to clicking START ALL SCANS.

-x, --stop

Stops Reasoning. This is equivalent to clicking STOP ALL SCANS.

User examples:

To start discovery:

tw_scan_control --start

To stop discovery:

tw_scan_control --stop

Adding discovery runs

Use the following common options with the tw_scan_control command line utility to add snapshot and scheduled scans and specify run details:

Command Line Option

Description

-a, --add

Adds a new scan range.

-r, --random

Scans the IP addresses (located in a file or listed at the command prompt) in random order.

-l, --scan-level=string

Specifies the scan level to use. This can be one of the following:

  • Sweep Scan—This will do a sweep scan, trying to determine what is at each endpoint in the scan range. It will attempt to login to a device to determine the device type.
  • Full Discovery—Retrieve all the default info for hosts, and complete full inference. This is the default if the option is not specified.

--company=companyname

Specifies the company name to use for a scan in a multitenant deployment.

-f, --file

Specifies a file or a list of files as arguments. They must be plain text files with a new line delimited list of IP addresses.

--label=label

Specifies the label for the scan.

--passphrase=passphrase

Specifies the vault passphrase to use.

--silent

Turns off informational messages.

User examples:

To specify an immediate scan of a single IP address:

tw_scan_control --add 192.168.0.1

To specify an immediate scan of a range of IP addresses:

 tw_scan_control --add 192.168.0.1-10

To specify an immediate scan of IP addresses listed in a file

tw_scan_control --add --file ~/scanlist

For user examples related to scheduled scans, see the Options to manage scheduled scans section.

Options to manage scheduled scans

By using the scheduled scan options with the tw_scan_control command line utility, you can perform the following:

Enabling and disabling scheduled discovery runs

Use the following common options with the tw_scan_control command line utility to enable or disable scheduled scans:

Command Line Option

Description

--enable

Enables the chosen scheduled scans.

--disable

Disables the chosen scheduled scans.

User examples:

To disable a scheduled scan: 

tw_scan_control --disable 6ee6e73209c64a4e9c0a0a8148a76f8b

To enable a scheduled scan which has been disabled: 

tw_scan_control --enable 6ee6e73209c64a4e9c0a0a8148a76f8b

Adding scheduled discovery runs

You can schedule discovery runs which are daily, weekly, and monthly for which the following options with the tw_scan_control command line utility are available:

Common options for scheduled discovery runs

Command Line Option

Description

--start-time=HH:MM

Sets the start time of a scheduled scan.

--end-time=HH:MM

Sets the end time of a scheduled scan.

--duration=DD:HH:MM

Sets the duration of scheduled scans.

--no-end-time

Sets the scheduled scan to run to its completion.

Options for scheduling daily discovery runs

Command Line Option

Description

--daily

Adds a daily scheduled scan.

User examples:

To specify a daily scheduled scan of a range of IP addresses with specified start and end time and label it TEST:

tw_scan_control --daily --start-time=21:30 --end-time=23:30 --label=TEST --add 192.168.0.1-10

To specify a daily scheduled scan of IP addresses listed in a file: 

tw_scan_control --daily --start-time=21:30 --end-time=23:30 --add --file ~/scanlist

To specify a daily scheduled scan of a range of IP addresses with specified start time and duration:

tw_scan_control --daily --start-time=21:30 --duration=00:06:30 --add 192.168.0.1-10

Options for scheduling weekly discovery runs

Command Line Option

Description

--weekly

Adds a weekly scheduled scan.

--weekly-start-week-days=WEEKDAYS

Sets the weekly scheduled scan start week day. The range of the start weekday is monday, tuesday, and so on.

--weekly-end-week-day=WEEKDAY

Sets the weekly scheduled scan end week day. The range of the end weekday is monday, tuesday, and so on.

User example:

To specify a weekly scheduled scan of a range of IP addresses with specified start time and day and specified end time and day:

tw_scan_control --weekly --weekly-start-week-days=monday --weekly-end-week-day=tuesday 
--start-time=21:30 --end-time=20:30 --add 192.168.0.1-10

Options for scheduling monthly discovery runs

Command Line Option

Description

--monthly

Adds a monthly scheduled scan.

--monthly-start-day=DAY

Sets the monthly scheduled scan start day. The range of the day is from 1 to 31.

--monthly-end-day=DAY

Sets the monthly scheduled scan end day. The range of the day is from 1 to 31.

--monthly-start-week=WEEK

Sets the monthly scheduled scan start week. The range of the week is first, second, third, fourth, and last.

--monthly-start-week-day=WEEKDAY

Sets the monthly scheduled scan start week day of the week. The range of the weekday is monday, tuesday, and so on.

User example:

To specify a monthly scheduled scan of a range of IP addresses with specified start time and day of the week and ends on completion of the scan:

tw_scan_control --monthly --monthly-start-week-day=monday --monthly-start-week=first 
--start-time=21:30 --no-end-time --add 192.168.0.1-10

Backward compatible options

Use the following backward compatible options with the tw_scan_control command line utility to add recurrent scans:

Command Line Option

Description

--recur-daily

Adds a daily recurrent range. This option specifies a recurrent range scan that must be modified with recurrence-duration=int and/or recurrence-start=int.

--recurrence-duration=int

Specifies the duration for the recurring scan to last (in hours).

--recurrence-start=int

Sets the start time for recurrent ranges (in hours) after midnight

Listing scheduled discovery runs

Use the following common options with the tw_scan_control command line utility to list scheduled discovery runs:

Command Line Option

Description

--list

Lists all scan ranges.

--list-full

Lists all scan ranges with all IP addresses.

Listing the scheduled discovery runs gives you information about them, such as the range ID corresponding to a run, whether the run has been enabled or disabled, the label and IP addresses or ranges associated with a run, and so on.

User example:

To list all scan ranges with all IP addresses:

tw_scan_control --list-full

Updating and deleting scheduled discovery runs

Use the following common options with the tw_scan_control command line utility to update or delete scheduled discovery runs:

Command Line Option

Description

--clear

Cancels any running scans and deletes all scheduled scans.

--remove

Removes chosen scan ranges.

--update=ID

Updates (edit) the specified scheduled discovery run. The discovery run is specified using its range ID which can be determined by running the list or list-full options.

User examples:

To remove a chosen scan range:

tw_scan_control --remove 6ee6e7320aa7c5716c140a8148a76f8b

To update a chosen scheduled scan:

  • Let us assume that you have set the following daily scheduled scan for an IP range where the start time is 14:30 and the end time is 17:30:
tw_scan_control --daily --start-time=14:30 --end-time=17:30 --add 192.168.0.1-10

Following are examples of updating the above scheduled scan.

    • To update the start time to 20:30 and the end time to 23:50, you will run the following command:

      tw_scan_control --daily --start-time=20:30 --end-time=23:50 
      --update=6ee6e7321031ae6a6fb80a8148a76f8b 192.168.0.1-10
    • To update it from a daily to a weekly scheduled scan, which starts on Monday at 07:30 and ends on Tuesday at 11:50, you will run the following command:

      tw_scan_control --weekly --weekly-start-week-days=monday --weekly-end-week-day=tuesday 
      --start-time=07:30 --end-time=11:50 --update=6ee6e732105205be37020a8148a76f8b 192.168.0.1-10

Overlapping of scheduled scans and excludes

In the case of permanent excludes, discovery of the excluded endpoints never starts. However, in the case of an overlap of scheduled scans and scheduled excludes, the following behavior is expected:

  • If a scheduled exclude overlaps with a scheduled scan, discovery of the excluded endpoints will not start until the scheduled exclude is no longer in effect.
  • If the scheduled exclude ends before the scheduled scan end time, discovery of the excluded endpoints can start.
  • If the scheduled exclude ends after the scheduled scan end time, the excluded endpoints will wait until the next time the scheduled scan runs.
  • If one or more scheduled excludes overlap completely with a scheduled scan, the excluded endpoints will behave like permanent excludes. This is to prevent it from waiting forever to discover those excluded endpoints that it will never be able to scan.
  • If a scheduled exclude is active and a snapshot scan is running, any excluded endpoint will be skipped by the scan and will have an excluded end state.

Deprecated utility: tw_injectip

The tw_injectip utility is now deprecated and might be removed in future releases. Its functionality is available in the tw_scan_control utility which has all of the same options.

Related topics

 

Was this page helpful? Yes No Submitting... Thank you
  • No labels

1 Comment

  1. Hi,

    Can we get sample content of a scanlist text file with both examples:

    • IP address
    • IP range
© Copyright 2004 - 2018 BMC Software, Inc.
Legal notices