The tw_scan_control utility enables you to scan IP ranges using the command line.


Use the BMC Atrium Discovery user interface to perform the functionality provided by the tw_scan_control command line utility (see Controlling discovery). If you choose to run the utility, read the documentation in this section to learn its usage and to understand the risks and potential impact on your environment.

To use the utility, type the following command at the $TIDEWAY/bin/ directory:

tw_scan_control [options] range


  • range is a single IP address or range (for example, or, a space-separated list of IP addresses, a range of IP addresses, or a subnet (for example, 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.

Command Line Option



Specifies to remove all the recurrent ranges that are not currently being scanned from the Reasoning pipeline


Specify a company name to use for a scan in a multitenant deployment.


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


Specifies a label for the scan

--passphrase= passphrase

Specifies a vault passphrase to use

-r, --random

Specifies to scan the IP addresses (located in a file or listed at the command prompt) in random order


Specifies to add a daily recurrent range. This option specifies a recurrent range scan that must be modified with the --recurrence-duration and/or --recurrence-start options.


Specifies the duration that the recurring scan lasts (in hours).

--recurrence-start= int

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


Replace (edit) the specified scheduled discovery run. The discovery run is specified using its ID which can be determined using a search query like the following:
search IPRange where scan_type='Scheduled' show range_id,label. See below for examples.

-l, --scanLevel= arg

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

  • Sweep Scan: Performs a sweep scan, trying to determine what is at each endpoint in the scan range. Attempts to login to a device to determine the device type.
  • Full Discovery: Retrieve all the default information for hosts and complete full inference.
  • Default: Use the current default level.

    Scan levels Sweep Scan and Full Discovery should be quoted as they contain spaces.

-s, --start

Specfies that Reasoning will start. This is equivalent to clicking START ALL SCANS.

-x, --stop

Specifies that Reasoning will stop. This is equivalent to clicking STOP ALL SCANS.

-u, --username= username

Specfies the name of the BMC Atrium Discovery user. If a user is not specified, BMC Atrium Discovery uses the default, system.

User examples

In the following 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.


The utility is designed to handle only snapshot and daily scans; no weekly or monthly schedules are available within this tool. For this functionality, use the user interface.

Specifying an immediate scan of a single IP address

$TIDEWAY/bin/tw_scan_control --username system

Specifying an immediate scan of a single IP address at Sweep Scan level

$TIDEWAY/bin/tw_scan_control --username system -l 'Sweep Scan'

Specifying an immediate scan of a range of IP addresses

$TIDEWAY/bin/tw_scan_control --username system

Specifying an immediate scan of IP addresses listed in a file

$TIDEWAY/bin/tw_scan_control --username system --file ~/scanlist

Specifying a scheduled scan of IP addresses listed in a file at 03.00

$TIDEWAY/bin/tw_scan_control --username system --recur-daily 
     --recurrence-start=3 --file ~/scanlist

Specifying a two-hour scheduled scan of IP addresses listed in a file

$TIDEWAY/bin/tw_scan_control --username system --recur-daily 
     --recurrence-duration=2 --file ~/scanlist

Specifying a two-hour scheduled scan of IP addresses listed in a file and label it TEST

$TIDEWAY/bin/tw_scan_control --username system --recur-daily 
     --recurrence-duration=2 --label=TEST --file ~/scanlist

Replacing a discovery run

The following example illustrates how to find the ID of a scheduled discovery run and use it to update the label on a run. The way that this option works is to delete and replace the scan, so it is important to specify all essential parameters (recur-daily, recurrence-duration and/or recurrence-start, and a range).

  1. In the Enter Generic Query page, enter the following query:

    search IPRange where scan_type='Scheduled' show range_id, label
  2. Click Run Query.
  3. Copy the ID from the range that you want to replace and use it to specify the ID of the scan that you want to replace.
  4. Enter the command.
    This example illustrates how the system user replaces a specified scan with a daily six-hour scan of the range and a label of UPDATED.

    tw_scan_control -u system -p system --recur-daily --recurrence-duration=6 --label=UPDATED 
        --replace 85be3f2d9ef810d84c1089485c704129
Was this page helpful? Yes No Submitting... Thank you